contrib/jcr-ext/src/java/org/apache/jackrabbit/decorator/package.html - jackrabbit - Git at Google

 <body>
 Generic JCR decorator layer.
 <p>
 This package implements a generic decorator layer for the Content Repository
 for Java technology API (JCR). This layer can be used to add various extra
 functionality and responsibilities to existing JCR implementations without
 having to modify or even access the original source code. The decorator layer
 implemented by this package functions entirely on the JCR API level without
 any dependencies to an underlying implementation.
 <p>
 This decorator layer implements the Decorator design pattern on a package
 level for the entire javax.jcr package. A client only needs to decorate
 a top level Repository instance, and the decorator layer will automatically
 handle the decoration of all Session, Node, and other JCR objects acquired
 using the decorated repository.

 <h2>Usage of the decorator layer</h2>
 <p>
 To use the decorator layer, a client should first acquire a Repository
 reference using whatever mechanism supported by the repository implementation
 in use. Then the client needs to create a DecoratorFactory instance and use
 it to decorate the repository. The resulting repository decorator can then
 be used as a normal repository instance. All other decorator instantiation
 will then be handled internally by the decorator layer using the given
 decorator factory.
 <p>
 The following example code illustrates how the decorator layer is instantiated
 and used.
 <pre>
     // Acquire a repository instance normally
     Repository repo = ...;

     // Create the decorator layer
     DecoratorFactory factory = ...;
     Repository deco = factory.getRepositoryDecorator(repo);

     // Use the decorated repository via the normal JCR API
     Session session = deco.login();
     Node root = session.getRootNode();
     Node node = root.getNode(...);
     Property prop = node.getProperty(...);
 </pre>
 <p>
 The diagram below shows the object instances created by default
 by the above code.
 <p align="center">
 <img src="doc-files/instances.jpg">
 </p>

 <h2>Extending the decorator layer</h2>
 <p>
 The Factory design pattern used in the DecoratorFactory interface and the
 default decorator classes makes it easy to extend the functionality of the
 decorator layer. Specific decorator functionality can be added by subclassing
 the default decorators included in this package and providing a custom
 DecoratorFactory that uses these specific decorator classes instead of the
 defaults.
 <p>
 For example, a decorator for mapping user accounts between authentication
 realms could subclass the RepositoryDecorator and SessionDecorator classes
 and override the login() and impersonate() methods with custom functionality.
 The decorator implementation would also provide a customized DecoratorFactory
 for creating a decorator layer that uses the user account mapping
 functionality. The layer can then be wrapped on top of an existing
 repository implementation.
 <p>
 See the org.apache.jackrabbit.cache and org.apache.jackrabbit.trace packages
 for examples of such decorator implementations.
 </body>
	<body>
	Generic JCR decorator layer.
	<p>
	This package implements a generic decorator layer for the Content Repository
	for Java technology API (JCR). This layer can be used to add various extra
	functionality and responsibilities to existing JCR implementations without
	having to modify or even access the original source code. The decorator layer
	implemented by this package functions entirely on the JCR API level without
	any dependencies to an underlying implementation.
	<p>
	This decorator layer implements the Decorator design pattern on a package
	level for the entire javax.jcr package. A client only needs to decorate
	a top level Repository instance, and the decorator layer will automatically
	handle the decoration of all Session, Node, and other JCR objects acquired
	using the decorated repository.

	<h2>Usage of the decorator layer</h2>
	<p>
	To use the decorator layer, a client should first acquire a Repository
	reference using whatever mechanism supported by the repository implementation
	in use. Then the client needs to create a DecoratorFactory instance and use
	it to decorate the repository. The resulting repository decorator can then
	be used as a normal repository instance. All other decorator instantiation
	will then be handled internally by the decorator layer using the given
	decorator factory.
	<p>
	The following example code illustrates how the decorator layer is instantiated
	and used.
	<pre>
	// Acquire a repository instance normally
	Repository repo = ...;

	// Create the decorator layer
	DecoratorFactory factory = ...;
	Repository deco = factory.getRepositoryDecorator(repo);

	// Use the decorated repository via the normal JCR API
	Session session = deco.login();
	Node root = session.getRootNode();
	Node node = root.getNode(...);
	Property prop = node.getProperty(...);
	</pre>
	<p>
	The diagram below shows the object instances created by default
	by the above code.
	<p align="center">
	<img src="doc-files/instances.jpg">
	</p>

	<h2>Extending the decorator layer</h2>
	<p>
	The Factory design pattern used in the DecoratorFactory interface and the
	default decorator classes makes it easy to extend the functionality of the
	decorator layer. Specific decorator functionality can be added by subclassing
	the default decorators included in this package and providing a custom
	DecoratorFactory that uses these specific decorator classes instead of the
	defaults.
	<p>
	For example, a decorator for mapping user accounts between authentication
	realms could subclass the RepositoryDecorator and SessionDecorator classes
	and override the login() and impersonate() methods with custom functionality.
	The decorator implementation would also provide a customized DecoratorFactory
	for creating a decorator layer that uses the user account mapping
	functionality. The layer can then be wrapped on top of an existing
	repository implementation.
	<p>
	See the org.apache.jackrabbit.cache and org.apache.jackrabbit.trace packages
	for examples of such decorator implementations.
	</body>