Update of /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv3806/platform/container/impl/src/java/org/jicarilla/container
Modified Files:
CyclicDependencyException.java DefaultContainer.java
DefaultKeyRelayingContainer.java
DefaultKeyRelayingResolver.java DefaultResolver.java
NoPublicConstructorAvailableException.java
NoSatisfiableConstructorAvailableException.java
ResolverCallback.java SynchronizationUtil.java
UnsatisfiableDependencyException.java
Log Message:
lots of docs. No other changes.
Index: CyclicDependencyException.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/CyclicDependencyException.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- CyclicDependencyException.java 11 Jan 2004 11:56:24 -0000 1.5
+++ CyclicDependencyException.java 29 Feb 2004 19:21:35 -0000 1.6
@@ -26,6 +26,39 @@
package org.jicarilla.container;
/**
+ * <p>Exception that is thrown when a {@link Container} detects a cyclic
+ * dependency. A cyclic dependency occurs when the graph that describes the
+ * components and their dependency relationship contains a cycle.
+ * For example:</p>
+ *
+ * <pre>
+ * A --> B --> C --> D --+
+ * ^ | <-- cycle!
+ * | |
+ * +---------------------+
+ * </pre>
+ *
+ * <p>In code:</p>
+ *
+ * <pre>
+ * public classs AImpl implements A
+ * {
+ * public AImpl( B ) { ... }
+ * }
+ * public classs BImpl implements B
+ * {
+ * public BImpl( C ) { ... }
+ * }
+ * public classs CImpl implements C
+ * {
+ * public CImpl( D ) { ... }
+ * }
+ * public classs DImpl implements D
+ * {
+ * public DImpl( A ) { ... }
+ * }
+ * </pre>
+ *
* @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
* @version $Id$
*/
Index: DefaultContainer.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/DefaultContainer.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- DefaultContainer.java 10 Jan 2004 11:16:34 -0000 1.9
+++ DefaultContainer.java 29 Feb 2004 19:21:35 -0000 1.10
@@ -37,6 +37,15 @@
import java.util.Map;
/**
+ * <p>A straightforward implementation of the {@link Container} interface that
+ * is backed by a {@link Switch}. This implementation is not threadsafe, and
+ * will use a {@link SelectorSwitch} and a {@link DefaultResolver} if no
+ * alternatives are provided.</p>
+ *
+ * <p>You will normally not want to use this implementation directly, as the
+ * {@link DefaultKeyRelayingContainer} provides commonly needed additional
+ * functionality.</p>
+ *
* @todo weak references where appropriate
* @todo split container-impl into multiple jars
* @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
@@ -47,23 +56,49 @@
// ----------------------------------------------------------------------
// Properties
// ----------------------------------------------------------------------
+ /** A reverse mapping that's used to implement <code>release()</code>. */
protected Map m_instanceToAdapterMap;
+ /** The <em>core</em> of the container that maps keys to adapters. */
protected Switch m_switch;
+ /** The main <em>client interface</em> into the container. */
protected Resolver m_resolver;
// ----------------------------------------------------------------------
// Constructors
// ----------------------------------------------------------------------
+ /**
+ * Create a new instance using a {@link SelectorSwitch} and a
+ * {@link DefaultResolver} as the backend.
+ */
public DefaultContainer()
{
this( null );
}
+ /**
+ * Create a new instance using a {@link SelectorSwitch} and the provided
+ * resolver as the backend. Providing a resolver yourself is quite an
+ * advanced construct and may lead to improper or unexpected behaviour if
+ * the resolver does not adhere to the expected contracts. In particular,
+ * the resolver is expected to defer back to the container or its internal
+ * <code>Switch</code> for most funcitonality.
+ *
+ * @param resolver
+ */
public DefaultContainer( final Resolver resolver )
{
this( resolver, null );
}
+ /**
+ * Create a new instance using the provided resolver and switch as the
+ * backend. Providing these yourself is quite an advanced construct and may
+ * lead to improper or unexpected results if the resolver does not adhere
+ * to the specified contracts.
+ *
+ * @param resolver
+ * @param switcher
+ */
public DefaultContainer( final Resolver resolver, final Switch switcher )
{
setResolver( resolver );
@@ -75,18 +110,38 @@
// Interface: Container
// ----------------------------------------------------------------------
- public Container registerAdapter( final Selector selector, final Adapter adapter )
+ /**
+ * @see Container#registerAdapter(Selector, Adapter)
+ *
+ * @param selector
+ * @param adapter
+ * @return
+ */
+ public Container registerAdapter( final Selector selector,
+ final Adapter adapter )
{
doAddAdapter( selector, adapter );
return this;
}
+ /**
+ * @see Container#registerAdapter(Object, Adapter)
+ *
+ * @param key
+ * @param adapter
+ * @return
+ */
public Container registerAdapter( final Object key, final Adapter adapter )
{
doAddAdapter( key, adapter );
return this;
}
+ /**
+ * @see Container#registerAdapter(Object, Adapter)
+ *
+ * @return
+ */
public Resolver getResolver()
{
return m_resolver;
@@ -96,21 +151,43 @@
// Getters and Setters
// ----------------------------------------------------------------------
+ /**
+ * Returns {@link m_instanceToAdapterMap}. Overriding is not recommended.
+ *
+ * @return {@link m_instanceToAdapterMap}
+ */
protected Map getInstanceToAdapterMap()
{
return m_instanceToAdapterMap;
}
+ /**
+ * Sets {@link m_instanceToAdapterMap}. Direct usage is not recommended.
+ *
+ * @param instanceToAdapterMap the new {@link m_instanceToAdapterMap}
+ * value.
+ */
protected void setInstanceToAdapterMap( final Map instanceToAdapterMap )
{
m_instanceToAdapterMap = instanceToAdapterMap;
}
+ /**
+ * Returns {@link m_switch}. Overriding is not recommended.
+ *
+ * @return {@link m_switch}
+ */
protected Switch getSwitch()
{
return m_switch;
}
+ /**
+ * Sets {@link m_switch}. Direct usage is not recommended.
+ *
+ * @param switcher the new {@link m_switch} value, or null to set it to
+ * a new default implementation
+ */
protected void setSwitch( final Switch switcher )
{
if( switcher != null )
@@ -119,6 +196,12 @@
m_switch = new SelectorSwitch();
}
+ /**
+ * Sets {@link m_resolver}. Direct usage is not recommended.
+ *
+ * @param resolver the new {@link m_resolver} value, or null to set it to
+ * a new default implementation
+ */
protected void setResolver( final Resolver resolver )
{
if( resolver != null )
@@ -131,7 +214,16 @@
// Helper methods
// ----------------------------------------------------------------------
- protected void doAddAdapter( final Selector selector, final Object adapter )
+ /**
+ * Add a new adapter. If you are providing an {@link Adapter} instance,
+ * use the public {@link #registerAdapter(Selector,Adapter)} instead.
+ *
+ * @param selector
+ * @param adapter the new adapter. The {@link m_resolver current resolver}
+ * should know how to use this adapter.
+ */
+ protected void doAddAdapter( final Selector selector,
+ final Object adapter )
{
Assert.assertNotNull( "selector argument may not be null", selector );
Assert.assertNotNull( "adapter argument may not be null", adapter );
@@ -139,6 +231,17 @@
getSwitch().put( selector, adapter );
}
+ /**
+ * Add a new adapter. If you are providing an {@link Adapter} instance,
+ * use the public {@link #registerAdapter(Object,Adapter)} instead.
+ * Implements some special handling for some key types (ie classes and some
+ * kinds of strings); use {@link #doAddAdapter(Selector,Object)} to avoid
+ * this.
+ *
+ * @param key
+ * @param adapter the new adapter. The {@link m_resolver current resolver}
+ * should know how to use this adapter.
+ */
protected void doAddAdapter( final Object key, final Object adapter )
{
Assert.assertNotNull( "key argument may not be null", key );
@@ -174,15 +277,32 @@
// Inner Class: DefaultResolverCallback
// ----------------------------------------------------------------------
+ /**
+ * Straightforward implementation of {@link ResolverCallback} that defers
+ * to its parent {@link DefaultContainer} implementation for the required
+ * functionality.
+ */
protected class DefaultResolverCallback implements ResolverCallback
{
+ /** The container to delegate to. */
protected final DefaultContainer m_container = DefaultContainer.this;
+ /**
+ * @see ResolverCallback#getSwitch()
+ *
+ * @return
+ */
public Switch getSwitch()
{
return m_container.getSwitch();
}
+ /**
+ * @see ResolverCallback#providedInstance(Object,Object)
+ *
+ * @param instance
+ * @param adapter
+ */
public void providedInstance(
final Object instance, final Object adapter )
{
@@ -194,6 +314,12 @@
m_container.getInstanceToAdapterMap().put( instance, adapter );
}
+ /**
+ * @see ResolverCallback#returnedInstance(Object)
+ *
+ * @param component
+ * @throws Exception
+ */
public void returnedInstance( final Object component ) throws Exception
{
if( component == null )
Index: DefaultKeyRelayingContainer.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/DefaultKeyRelayingContainer.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- DefaultKeyRelayingContainer.java 8 Jan 2004 17:06:11 -0000 1.5
+++ DefaultKeyRelayingContainer.java 29 Feb 2004 19:21:35 -0000 1.6
@@ -25,11 +25,21 @@
==================================================================== */
package org.jicarilla.container;
+import org.jicarilla.framework.Assert;
import org.jicarilla.framework.Selector;
import org.jicarilla.framework.Switch;
/**
- *
+ * <p>A straightforward implementation of the {@link KeyRelayingContainer}
+ * interface that is backed by a {@link Switch}. This implementation is not
+ * threadsafe, and delegates most of its functionality to
+ * {@link DefaultContainer}.</p>
+ *
+ * <p>You will normally not want to use this implementation directly, as the
+ * {@link org.jicarilla.container.builder.Builder} interface and its
+ * {@link org.jicarilla.container.builder.DefaultBuilder} implementation
+ * provide a more convenient way to create and populate container
+ * instances.</p>
*
* @author <a href="mail at leosimons dot com">Leo Simons</a>
* @version $Id$
@@ -41,21 +51,38 @@
// Constructors
// ----------------------------------------------------------------------
+ /**
+ * @see DefaultContainer#DefaultContainer()
+ */
public DefaultKeyRelayingContainer()
{
// this is a shame, cause its expensive
super();
super.setResolver(
new DefaultKeyRelayingResolver(
- new DefaultKeyRelayingCallback()
+ new DefaultKeyRelayingResolverCallback()
)
);
}
+
+ /**
+ * @see DefaultContainer#DefaultContainer(Resolver)
+ *
+ * @param resolver
+ */
public DefaultKeyRelayingContainer( final Resolver resolver )
{
super( resolver );
}
- public DefaultKeyRelayingContainer( final Resolver resolver, final Switch switcher )
+
+ /**
+ * @see DefaultContainer#DefaultContainer(Resolver,Switch)
+ *
+ * @param resolver
+ * @param switcher
+ */
+ public DefaultKeyRelayingContainer( final Resolver resolver,
+ final Switch switcher )
{
super( resolver, switcher );
}
@@ -64,6 +91,13 @@
// Interface: KeyRelayingContainer
// ----------------------------------------------------------------------
+ /**
+ * @see KeyRelayingContainer#registerAdapter(Selector,KeyAwareAdapter)
+ *
+ * @param selector
+ * @param adapter
+ * @return
+ */
public KeyRelayingContainer registerAdapter( final Selector selector,
final KeyAwareAdapter adapter )
{
@@ -71,34 +105,62 @@
return this;
}
- public KeyRelayingContainer registerAdapter( final Object key, final KeyAwareAdapter adapter )
+ /**
+ * @see KeyRelayingContainer#registerAdapter(Object,KeyAwareAdapter)
+ *
+ * @param key
+ * @param adapter
+ * @return
+ */
+ public KeyRelayingContainer registerAdapter( final Object key,
+ final KeyAwareAdapter adapter )
{
doAddAdapter( key, adapter );
return this;
}
// ----------------------------------------------------------------------
- // Inner Class: DefaultKeyRelayingCallback
+ // Inner Class: DefaultKeyRelayingResolverCallback
// ----------------------------------------------------------------------
- protected class DefaultKeyRelayingCallback
+ /**
+ * Extension of {@link DefaultContainer.DefaultResolverCallback} that
+ * implements handlign of {@link KeyAwareAdapter}s.
+ */
+ protected class DefaultKeyRelayingResolverCallback
extends DefaultContainer.DefaultResolverCallback
{
+ /**
+ * @see DefaultContainer.DefaultResolverCallback#providedInstance(Object,Object)
+ *
+ * @param instance
+ * @param adapter
+ */
public void providedInstance(
final Object instance, final Object adapter )
{
- if( adapter instanceof Adapter )
- super.providedInstance( instance, adapter );
- else
- m_instanceToAdapterMap.put( instance, adapter );
+ Assert.assertTrue(
+ "DefaultContainer can only handle adapters that " +
+ "implement the Adapter or KeyAwareAdapter interface!",
+ adapter instanceof Adapter ||
+ adapter instanceof KeyAwareAdapter );
+
+ m_container.getInstanceToAdapterMap().put( instance, adapter );
}
+ /**
+ * @see DefaultContainer.DefaultResolverCallback#returnedInstance(Object)
+ *
+ * @param component
+ * @throws Exception
+ */
public void returnedInstance( final Object component ) throws Exception
{
if( component == null )
return;
- final Object adapter = m_instanceToAdapterMap.remove( component );
+ final Object adapter =
+ m_container.getInstanceToAdapterMap().remove( component );
if( adapter != null )
{
if( adapter instanceof Adapter )
Index: DefaultKeyRelayingResolver.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/DefaultKeyRelayingResolver.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- DefaultKeyRelayingResolver.java 10 Jan 2004 12:12:26 -0000 1.4
+++ DefaultKeyRelayingResolver.java 29 Feb 2004 19:21:35 -0000 1.5
@@ -28,7 +28,8 @@
/**
- *
+ * <p>A simple extension of {@link DefaultResolver} that adds handling for
+ * {@link KeyAwareAdapter}s.
*
* @author <a href="mail at leosimons dot com">Leo Simons</a>
* @version $Id$
@@ -39,6 +40,11 @@
// Constructors
// ----------------------------------------------------------------------
+ /**
+ * @see DefaultResolver#DefaultResolver(ResolverCallback)
+ *
+ * @param callback
+ */
public DefaultKeyRelayingResolver( final ResolverCallback callback )
{
super( callback );
@@ -48,6 +54,13 @@
// Helper Methods
// ----------------------------------------------------------------------
+ /**
+ * @see DefaultResolver#getInstanceFromAdapter(Object,Object)
+ *
+ * @param adapter
+ * @param key
+ * @return
+ */
protected Object getInstanceFromAdapter(
final Object adapter, final Object key )
{
Index: DefaultResolver.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/DefaultResolver.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- DefaultResolver.java 11 Jan 2004 12:18:20 -0000 1.5
+++ DefaultResolver.java 29 Feb 2004 19:21:35 -0000 1.6
@@ -34,9 +34,13 @@
import java.util.List;
/**
+ * <p>A Straightforward implementation of the {@link Resolver} interface that
+ * is backed by a {@link ResolverCallback} instance. This implementation is not
+ * thread safe.</p>
*
+ * <p>You will normally not want to create instances of this class directly.
+ * Rather, let the associated {@link DefaultContainer} worry about that.</p>
*
- * @todo improve the exception handling
* @author <a href="mail at leosimons dot com">Leo Simons</a>
* @version $Id$
*/
@@ -45,11 +49,17 @@
// ----------------------------------------------------------------------
// Properties
// ----------------------------------------------------------------------
+ /** The callback to the container. */
protected ResolverCallback m_callback;
// ----------------------------------------------------------------------
// Constructors
// ----------------------------------------------------------------------
+ /**
+ * Create a new instance using the provided callback.
+ *
+ * @param callback value for {@link m_callback}.
+ */
public DefaultResolver( final ResolverCallback callback )
{
setCallback( callback );
@@ -59,11 +69,21 @@
// Getters and Setters
// ----------------------------------------------------------------------
+ /**
+ * Returns {@link m_callback}. Overriding is not recommended.
+ *
+ * @return {@link m_callback}
+ */
protected ResolverCallback getCallback()
{
return m_callback;
}
+ /**
+ * Sets {@link m_callback}. Direct usage is not recommended.
+ *
+ * @param callback the new {@link m_callback} value.
+ */
public void setCallback( final ResolverCallback callback )
{
Assert.assertNotNull( "callback argument may not be null", callback );
@@ -74,6 +94,12 @@
// Interface: Resolver
// ----------------------------------------------------------------------
+ /**
+ * @see {@link Resolver#get(Object)
+ *
+ * @param key
+ * @return
+ */
public Object get( final Object key )
{
Assert.assertNotNull( "key argument may not be null", key );
@@ -85,6 +111,12 @@
return getInstanceFromAdapter( adapter, key );
}
+ /**
+ * @see {@link Resolver#getAll(Object)
+ *
+ * @param key
+ * @return
+ */
public Object[] getAll( final Object key )
{
Assert.assertNotNull( "key argument may not be null", key );
@@ -96,6 +128,12 @@
return instances.toArray();
}
+ /**
+ * @see {@link Resolver#contains(Object)
+ *
+ * @param key
+ * @return
+ */
public boolean contains( final Object key )
{
if( key == null )
@@ -107,6 +145,12 @@
return false;
}
+ /**
+ * @see {@link Resolver#releaseInstance(Object)}
+ *
+ * @param component
+ * @throws Exception
+ */
public void releaseInstance( final Object component ) throws Exception
{
getCallback().returnedInstance( component );
@@ -116,6 +160,15 @@
// Helper Methods
// ----------------------------------------------------------------------
+ /**
+ * Helper method that is called from {@link #get(Object)} to retrieve
+ * an instance from an adapter and add that instance to the container
+ * through {@link m_callback}.
+ *
+ * @param adapter
+ * @param key
+ * @return
+ */
protected Object getInstanceFromAdapter(
final Object adapter, final Object key )
{
@@ -136,6 +189,14 @@
return instance;
}
+ /**
+ * Helper method that is called form {@link #getAll(Object)} to retrive
+ * a list of instances from the switch provided by {@link m_callback}
+ * and add those instances to to the container.
+ *
+ * @param key
+ * @return
+ */
protected List getInstanceListFromKey( final Object key )
{
Index: NoPublicConstructorAvailableException.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/NoPublicConstructorAvailableException.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- NoPublicConstructorAvailableException.java 10 Jan 2004 10:49:36 -0000 1.5
+++ NoPublicConstructorAvailableException.java 29 Feb 2004 19:21:35 -0000 1.6
@@ -1,19 +1,35 @@
package org.jicarilla.container;
/**
+ * Exception that is thrown when an {@link Adapter} or {@link Factory}
+ * cannot create an instance because there is no public constructor available.
+ * This usually indicates a mistake made during assembly.
+ *
* @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
* @version $Id$
*/
public class NoPublicConstructorAvailableException
extends JicarillaInstantiationException
{
+ /** The class that has no public constructor. */
protected final Class m_problematicClass;
+ /**
+ * Creates a new instance identifying the specified class as the problem.
+ *
+ * @param clazz the class that has no public constructor.
+ */
public NoPublicConstructorAvailableException( final Class clazz )
{
super( clazz.getName() + "has no public constructors!" );
m_problematicClass = clazz;
}
+
+ /**
+ * Retrieve the class that has no public constructor.
+ *
+ * @return
+ */
public Class getProblematicClass()
{
return m_problematicClass;
Index: NoSatisfiableConstructorAvailableException.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/NoSatisfiableConstructorAvailableException.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- NoSatisfiableConstructorAvailableException.java 11 Jan 2004 11:56:24 -0000 1.5
+++ NoSatisfiableConstructorAvailableException.java 29 Feb 2004 19:21:35 -0000 1.6
@@ -29,14 +29,29 @@
import java.util.Set;
/**
+ * Exception that is thrown when an {@link Adapter} or {@link Factory}
+ * cannot create an instance because none of its public constructors has
+ * an argument list that can be properly satisfied.
+ *
* @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
* @version $Id$
*/
public class NoSatisfiableConstructorAvailableException
extends UnsatisfiableDependencyException
{
+ /** The least demanding constructor that was still problematic. */
private final Constructor m_problematicConstructor;
+ /**
+ * Create a new instance identifying the specified constructor of the
+ * specified class as the problem because the specified arguments could
+ * not be provided.
+ *
+ * @param clazz the class of which no instance could be created.
+ * @param constructor the constructor that could not be called properly.
+ * @param unsatisfiedDependencies the arguments that could not be provided
+ * to the constructor.
+ */
public NoSatisfiableConstructorAvailableException( final Class clazz,
final Constructor constructor, final Set unsatisfiedDependencies )
{
@@ -50,6 +65,11 @@
m_problematicConstructor = constructor;
}
+ /**
+ * Returns the constructor that could not be called properly.
+ *
+ * @return the constructor that could not be called properly.
+ */
public Constructor getProblematicConstructor()
{
return m_problematicConstructor;
Index: ResolverCallback.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/ResolverCallback.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- ResolverCallback.java 6 Jan 2004 22:18:03 -0000 1.1
+++ ResolverCallback.java 29 Feb 2004 19:21:35 -0000 1.2
@@ -28,14 +28,46 @@
import org.jicarilla.framework.Switch;
/**
- * Not part of the public API because its really an implementation detail.
+ * Represents the contract between a {@link DefaultContainer} or
+ * {@link DefaultKeyRelayingContainer} and the associated {@link Resolver}.
+ * This class is not part of the public API on purpose -- it is an
+ * implementation detail associated with the way the default implementation
+ * package divides functionality.
*
* @author <a href="mail at leosimons dot com">Leo Simons</a>
* @version $Id$
*/
public interface ResolverCallback
{
+ /**
+ * Called by the resolver to retrieve a reference to the {@link Switch}
+ * that contains the mapping from keys to adapters used by the container.
+ * The reference that is retrieved should not be stored in the resolver.
+ *
+ * @return the reference to the switch that contains the mapping from keys
+ * to adapters used by the container.
+ */
Switch getSwitch();
+
+ /**
+ * Called by the resolver whenever it retrieves an instance from an
+ * adapter that it retrieved from the switch provided by
+ * {@link #getSwitch()}.
+ *
+ * @param instance the instance that was retrieved.
+ * @param adapter the adapter from which the instance was retrieved.
+ */
void providedInstance( Object instance, Object adapter );
+
+ /**
+ * Called by the resolver whenever an instance retrieved from an adapter
+ * that was retrieved from the switch provided by {@link #getSwitch()}
+ * needs to be returned.
+ *
+ * @param instance the instance that was retrieved.
+ * @throws Exception if {@link Adapter#releaseInstance(Object)}
+ * throws an exception. The container should not normally throw
+ * an Exception otherwise.
+ */
void returnedInstance( Object instance ) throws Exception;
}
Index: SynchronizationUtil.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/SynchronizationUtil.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- SynchronizationUtil.java 8 Jan 2004 17:06:11 -0000 1.5
+++ SynchronizationUtil.java 29 Feb 2004 19:21:35 -0000 1.6
@@ -29,33 +29,83 @@
import org.jicarilla.framework.Selector;
/**
+ * <p>Utility methods that create thread safe wrappers around the core
+ * abstractions of this package. Uses synchronization on mutexes around method
+ * calls; the arguments provided to the various methods are not modified
+ * themselves. You should take care to ensure that no references to the
+ * unwrapped objects are kept because method calls on those objects might
+ * produce concurrency problems. For example, the followin should <em>not</em>
+ * be used:</p>
+ *
+ * <pre>
+ * Adapter adapter = new DefaultAdapter();
+ * Adapter synchronizedAdapter =
+ * SynchronizationUtil.synchronizedAdapter(adapter);
+ * doThings(adapter);
+ * doThingsInANewThread(synchronizedAdapter);
+ * </pre>
+ *
+ * <p>Rather, use a coding pattern like the following:</p>
+ *
+ * <pre>
+ * Adapter adapter =
+ * SynchronizationUtil.synchronizedAdapter( new DefaultAdapter() );
+ * </pre>
+ *
* @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
* @version $Id$
*/
public class SynchronizationUtil
{
+ /**
+ * Create a thread safe version of an {@link Adapter} by wrapping the
+ * provided instance.
+ *
+ * @param adapter the adapter to wrap.
+ * @return an adapter that is safe for concurrent use.
+ */
public static Adapter synchronizedAdapter( final Adapter adapter )
{
return synchronizedAdapter( adapter, new Object() );
}
- protected static Adapter synchronizedAdapter( final Adapter adapter, final Object mutex )
+ /**
+ * Create a thread safe version of an {@link Adapter} by wrapping the
+ * provided instance, and synchronizing on the provided mutex.
+ *
+ * @param adapter the adapter to wrap.
+ * @param mutex the object to synchronize on.
+ * @return an adapter that is safe for concurrent use.
+ */
+ protected static Adapter synchronizedAdapter( final Adapter adapter,
+ final Object mutex )
{
return new SynchronizedComponentAdapter( adapter, mutex );
}
+ /**
+ * Create a thread safe version of a {@link Container} by wrapping the
+ * provided instance.
+ *
+ * @param delegate the container to wrap.
+ * @return a container that is safe for concurrent use.
+ */
public static Container synchronizedContainer( final Container delegate )
{
return new SynchronizedContainer( delegate );
}
+ /**
+ * Synchronizing wrapper around an <code>Adapter</code>.
+ */
protected static class SynchronizedComponentAdapter
implements Adapter
{
protected final Adapter m_delegate;
protected final Object m_mutex;
- public SynchronizedComponentAdapter( final Adapter delegate, final Object mutex )
+ protected SynchronizedComponentAdapter( final Adapter delegate,
+ final Object mutex )
{
Assert.assertNotNull( "delegate argument may not be null", delegate );
Assert.assertNotNull( "mutex argument may not be null", mutex );
@@ -80,6 +130,11 @@
}
}
+ /**
+ * Synchronizing wrapper around a <code>Container<code>. Performs "deep
+ * synchronization" by also synchronizing contained adapters and
+ * resolvers on a common mutex.
+ */
protected static class SynchronizedContainer implements Container
{
protected final Container m_delegate;
@@ -122,6 +177,9 @@
}
}
+ /**
+ * Synchronizing wrapper around a <code>Resolver</code>.
+ */
protected static class SynchronizedResolver implements Resolver
{
protected final Resolver m_delegate;
Index: UnsatisfiableDependencyException.java
===================================================================
RCS file: /cvsroot/jicarilla/jicarilla-sandbox/platform/container/impl/src/java/org/jicarilla/container/UnsatisfiableDependencyException.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- UnsatisfiableDependencyException.java 15 Jan 2004 23:29:11 -0000 1.7
+++ UnsatisfiableDependencyException.java 29 Feb 2004 19:21:35 -0000 1.8
@@ -28,15 +28,29 @@
import java.util.Set;
/**
+ * Exception that is thrown when an {@link Adapter} or {@link Factory}
+ * cannot create an instance because the instance has a dependency that
+ * cannot be satisfied.
+ *
* @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
* @version $Id$
*/
public class UnsatisfiableDependencyException
extends JicarillaInstantiationException
{
+ /** the class of which no instance could be created. */
protected final Class m_problematicClass;
+ /** the arguments that could not be provided to the constructor. */
protected final Set m_unsatisfiedDependencies;
+ /**
+ * Create a new instance identifying the specified class as the problem
+ * because the specified dependencies could not be provided.
+ *
+ * @param clazz the class of which no instance could be created.
+ * @param unsatisfiedDependencies the arguments that could not be provided
+ * to the constructor.
+ */
public UnsatisfiableDependencyException( final Class clazz,
final Set unsatisfiedDependencies )
{
@@ -48,6 +62,17 @@
// throw new NullPointerException("unsatisfiedDependencies");
}
+ /**
+ * Create a new instance identifying the specified class as the problem
+ * because the specified dependencies could not be provided, with the
+ * specified custom message.
+ *
+ * @param clazz the class of which no instance could be created.
+ * @param unsatisfiedDependencies the arguments that could not be provided
+ * to the constructor.
+ * @param message the message containing a further description of the
+ * problem.
+ */
public UnsatisfiableDependencyException( final Class clazz,
final Set unsatisfiedDependencies, final String message )
{
@@ -60,11 +85,21 @@
m_unsatisfiedDependencies = unsatisfiedDependencies;
}
+ /**
+ * Returns the dependencies that could not be satisfied.
+ *
+ * @return the dependencies that could not be satisfied.
+ */
public Set getUnsatisfiedDependencies()
{
return m_unsatisfiedDependencies;
}
+ /**
+ * Returns the class that could not be instantiated.
+ *
+ * @return the class that could not be instantiated.
+ */
public Class getProblematicClass()
{
return m_problematicClass;
-------------------------------------------------------
SF.Net is sponsored by: Speed Start Your Linux Apps Now.
Build and deploy apps & Web services for Linux with
a free DVD software kit from IBM. Click Now!
http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click
lmpx.com only provides a reader for public news (NNTP) servers. It is not
affiliated with the servers or forums shown here and is not responsible for
the content of articles, which is written by their respective authors.