org.sapia.resource.include
Class IncludeState

java.lang.Object
  org.sapia.resource.include.IncludeState

public class IncludeState
extends Object

This class is used to perform file-includes programmatically. It internally keeps a stack of IncludeContext instances that correspond to recursive resource-inclusion operations.

Internally, state is maintained on a per-thread and per-application basis. This allows multiple threads to perform resource inclusion operations in parallel, and isolates different applications/frameworks so that resource inclusion does not conflict (this framework could be used by a given framework X, that could itself be used by a given framework Y, also using this framework...).

In order to use this class, applications must:

1. Extend the IncludeContext class and overridde the IncludeContext.doInclude(InputStream, Object) method.
2. Implement an IncludeContextFactory, that will create instances of the above IncludeContext.
3. Implement a ResourceCapable class. An instance of that class is in charge of resolving resources (see ResourceCapable for details).

Then, the first step in using this class in order to perform resource inclusion is to create an IncludeConfig instance that is kept by the application and can be used for multiple resource-inclusion operations:

 IncludeConfig config = IncludeState.createConfig("org.acme.myapp", myIncludeContextFactory, myResourceCapableObject);
 

It should be noted that the createConfig(String, IncludeContextFactory, ResourceCapable) method takes a so-called "application key" has an argument. This is because this class could be used by multiple applications/frameworks residing within the same VM and classloader... Provided these frameworks use this class concurrently, this could pose problem. Therefore, the registering inclusion state under a given application key, and to the current thread, ensures that no conflict occur.

Note that the best way to guarantee uniqueness of application keys is to use root package names.

Once an IncludeConfig has been created, use it with this class to perform resource-inclusion:

 Object someObject = IncludeState.createContext("file:conf/main.xml", config).include();
 

The framework handles relative file resolution. Therefore, if the following code comes after the previous one, the resource will be resolved relatively to "conf/main.xml" (meaning that it will correspond to "conf/includes/database.xml"):

 Object someObject = IncludeState.createContext("includes/database.xml", config).include();
 

This framework provides a Resource primitive. Multiple implementations exist, that correspond to the following protocol schemes:

• file (e.g.: file:conf/main.xml, file:/home/foo/conf/main.xml).
• resource (e.g.: resource:/org/acme/myapp/main.xml).
• http

A ResourceCapable implementation is provided: the ResourceHandlerChain class, which implements a chain of responsibility that encapsulates ResourceHandlers. You could use these implementations as follows:

 ResourceHandlerChain resources = new ResourceHandlerChain();
 resource.append(new FileResourceHanler());
 resource.append(new ClassPathResourceHanler());
 resource.append(new UrlPathResourceHanler());
 
 IncludeConfig config = IncludeState.createConfig("org.acme.myapp", myIncludeContextFactory, resources);
 

Author:

yduchesne

See Also:

IncludeContext, IncludeContextFactory, IncludeConfig

Method Summary

static IncludeConfig	createConfig(String appKey, IncludeContextFactory fac, ResourceCapable resources)
static IncludeContext	createContext(String uri, IncludeConfig config) This method internally creates an IncludeContext that it pushes on its internall include stack before returning it.
static IncludeContext	currentContext(String appKey)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createConfig

public static IncludeConfig createConfig(String appKey,
                                         IncludeContextFactory fac,
                                         ResourceCapable resources)

Parameters:

appKey - the application key

fac - an IncludeContextFactory.

resources - a ResourceCapable instance.

Returns:

an IncludeConfig.

currentContext

public static IncludeContext currentContext(String appKey)

Parameters:

appKey - the application key

Returns:

this instance's current IncludeContext, or null if no such instance exists (i.e.: none has been stacked).

createContext

public static IncludeContext createContext(String uri,
                                           IncludeConfig config)

This method internally creates an IncludeContext that it pushes on its internall include stack before returning it.

Parameters:

uri - the URI for which to create a new IncludeContext.

config - the IncludeConfig to use to create the context.

Returns:

a new IncludeContext.