Initialization Framework
From Tupelo Wiki
Tupelo configuration is complex, so it provides a simple, generic mechanism for encapsulating configuration information. Configuration information can be published as an XML file so that clients need only a URL and authentication information to establish a Tupelo session.
| Table of contents |
Using the initialization framework
The initialization framework is used by applications that need to make calls against Tupelo's metadata, data, or access control services. The following sections describe the API calls that an application uses to establish the necessary context and acquire the service facades that it can use to interact with Tupelo. The API's described in the following sections are also summarized graphically here (http://dlt.ncsa.uiuc.edu/tupelo/doc/newInitFramework.pdf).
Locating a configuration file
Tupelo configuration files can contain any number of named initialization contexts. Contexts are identified using URL's in the following form:
{configurationFileUrl}#{contextName}
For instance, the following URL
http://www.mysite.org/tupelo/conf.xml#ogsi
locates the context called "ogsi" in the configuration file at http://www.mysite.org/tupelo/conf.xml
Tupelo's initialization framework can be extended to interoperate with arbitrary mechanisms for serializing configuration information; it currently uses Spring (http://www.springframework.org/).
Getting an application context
An application context contains all the information Tupelo needs to initialize its components on behalf of an application. Using Tupelo requires acquiring an application context. Here's how.
To get a context from a Spring configuration file, use SpringContextFactory:
import org.tupeloproject.framework.Context;
import org.tupeloproject.framework.spring.SpringContextFactory;
...
SpringContextFactory scf = new SpringContextFactory("http://www.mysite.org/tupelo/conf.xml#ogsi");
Context c = scf.newContext();
SpringContextFactory will attempt to read file:// URL's from the local filesystem. If it cannot find the file in the local filesystem, it will attempt to read it from the classpath. The Tupelo distribution creates a file, build/lib/tupelo-spring.jar, that contains the Spring configuration file generated during the build process; the URL of that file is file:///tupelo-spring.xml.
Getting a session context
Most Tupelo API's require authentication. A session context extends an application context by adding authentication information. This is typically constructed by the application once it has located and acquired an application context, and the user's identity.
import org.tupeloproject.framework.Context;
import org.tupeloproject.framework.spring.SpringContextFactory;
import org.tupeloproject.init.SessionContext;
...
SpringContextFactory scf = new SpringContextFactory("http://www.mysite.org/tupelo/conf.xml#ogsi");
Context c = scf.newContext();
SessionContext sc = new SessionContext(c, identity);
Getting a service facade
To interact with Tupelo, applications typically use service facades, which provide a number of convenience methods and facilities that simplify and aggregate Tupelo's lower-level API's. To constuct a service facade, all you need is a session context:
import org.tupeloproject.framework.Context;
import org.tupeloproject.framework.spring.SpringContextFactory;
import org.tupeloproject.init.SessionContext;
import org.tupeloproject.metadata.service.MetadataServiceFacade;
...
SpringContextFactory scf = new SpringContextFactory("http://www.mysite.org/tupelo/conf.xml#ogsi");
Context c = scf.newContext();
SessionContext sc = new SessionContext(c, identity);
MetadataServiceFacade md = new MetadataServiceFacade(sc);
How to write a configurable implementation
Inside Tupelo, implementations must provide several facilities in order to be configurable by the initialization framework. This is only of interest to developers wishing to extend Tupelo, or application developers who are curious about how configuration information is handled by the Tupelo implementation, or developers who would like to reuse Tupelo's initialization framework in other projects.
Basically, you must implement the callback API of org.tupeloproject.framework.Handler. Inside the callback API, the handler is provided with an org.tupeloproject.framework.Context containing configuration information, and an implementation instance of some arbitrary class (which is specified in the Spring configuration file).
For more details, see the Tupelo API Javadoc, here (http://dlt.ncsa.uiuc.edu/javadoc/tupelo/); specifically, org.tupeloproject.framework.Context (http://dlt.ncsa.uiuc.edu/javadoc/tupelo/org/tupeloproject/framework/Context.html).
