Java Doc for Adapter.java in  » Web-Server » JicarillaHTTP » org » jicarilla » container » Java Source Code / Java DocumentationJava Source Code and Java Documentation

An adapter is used to plug "something" into a Container . This "something" can actually be anything (since Adapter.getInstance() returns an Object and Adapter.releaseInstance(Object) is not required to do anything. The use of the word "adapter" refers to an analogy between your software design and home electronics. Just like many home electronics devices need a custom power adapter to be plugged into a power socket, your objects need an adapter to be plugged into a container.

There's several common kinds of adapters:

• factories. These will usually create a new instance when getInstance() is called, and will destroy the instance when releaseInstance() is called.
• directories. These will not create a new instance themselves, but rather look one up in some kind of registry or directory, for example from a Resolver or JNDI.
• adapter-adapters. These will usually not do much, but they will provide an interface to some other adapter that the container can use. In the home electronics analogy, you may want to use a home electronics device whose plug doesn't fit in your power socket (like European plugs in an American power socket). In that case, you will usually put in place a small power plug adapter between the power plug and the power socket.

Of course, other types of adapters from those mentioned may exist.

Adapters are normally associated with some kind of selection mechanism inside the container. In the case of the Container interface. that selection mechanism is either a key (similar to the keys used in java.util.Map maps or an instance of a org.jicarilla.lang.Selector .

Note that it is usually possible to use an adapter without using a container. When doing so, observe these contracts:

• method call ordering. You may not call releaseInstance() until you have called getInstance() at least once.
• method call pairing. You should call releaseInstance() once for every time you call getInstance(), and the parameter to releaseInstance() must be the object you received from getInstance().

(note that it is legal to call getInstance() multiple times in a row and then call releaseInstance() multiple times in a row.)

Also note that some Adapter implementations may be less strict about these rules. See the documentation for those implementations to be sure.