WrapperBooster (DRAGOS Core 1.0-SNAPSHOT API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

i3.dragos.gm.core
Class WrapperBooster

java.lang.Object
  i3.dragos.gm.core.WrapperBooster

All Implemented Interfaces:: Wrapper

public class WrapperBooster
extends java.lang.Object
implements Wrapper
extends java.lang.Object
implements Wrapper

A Wrapper enhancer to be used by core graph model implementations.

Introduction and a warning

WrapperBooster is not intended for use by extensions or applications, only by back-end implementations!

But since it implements the Wrapper interface, it may also be used as a simple caching wrapper, which might make sense if the back-end does not employ caching (be it through WrapperBooster or a custom mechanism). However, the "switchable wrapping" feature should not be used on any level above the back-end, unless you are absolutely sure you understand all interactions and can foresee or control any future modifications that might be affected by this!

How WrapperBooster works

It provides improved performance and ease of use through the following mechanisms:

Switchable Wrapping

It makes sense to build certain methods upon others. But according to the general contract, these methods return wrapped entities, entity classes or attributes. To avoid the associated overhead, you can either write non-wrapping variants for internal use only, which bloats the interface and code, or you can simply use WrapperBooster, which allows you to switch off wrapping temporarily.

The recommended way to do so is:

 WrapperBooster wb = ...;
 // force the mode you need 
 boolean wrappingActive = wb.(de)activateWrapping();
 // perform your operations
 [...]
 // restore the previous mode
 wb.setWrapping(wrappingActive);

Caching

WrapperBooster keeps a cache of objects it has wrapped, and always consults this cache first, calling the actual wrappers only if necessary. While the direct runtime effects may be negligible depending on the number and complexity of the wrappers, the main effect is that a lot less copies (as defined by equals(Object)) of a single object are created, resulting in less memory usage / GC activity.

Pre-Wrappers

WrapperBooster makes using proxies easier, by allowing a "pre-wrapper" to be set, which will be called before the actual wrapper. See the "Guide to Wrappers" for more information.

How to use WrapperBooster

You should try to follow these suggestions (doc comments ommited):

Integration into GraphPool

 // make sure to initialize these two so they are never null!
 private Wrapper wrapper;
 private WrapperBooster wrapperBooster;
 
 public Wrapper getWrapper() {
     return wrapper;
 }
 
 // public so it can be accessed by the schema
 public WrapperBooster getWrapperBooster() {
     return wrapperBooster;
 }
 
 public void setWrapper(Wrapper w) {
     this.wrapper = w;
     
     // save reference to the old WrapperBooster
     WrapperBooster oldWrapperBooster = this.wrapperBooster;
     
     // create and set the new WrapperBooster
     // add your preWrapper as a parameter here if you need one
     this.wrapperBooster = new WrapperBooster(w);     
     
     // clear caches of old WrapperBooster (if any) to free memory
     if (null != oldWrapperBooster) {
         oldWrapperBooster.clearCaches();
     }
 }

Wrapping entities

Use it just like you would use the ordinary wrapper. Instead of

 graphPool.getWrapper().wrapGraphEntity(g);

you would write

 graphPool.getWrapperBooster().wrapGraphEntity(g);

Deactivating wrapping temporarily

If you want to call another method internally and do not need its results in a wrapped form, use

 graphPool.getWrapperBooster().deactivateWrapping();
 Collection = someMethod();
 graphPool.getWrapperBooster().activateWrapping();

Note that this also affects the pre-wrapper, which is deactivated, too! If you need a different behaviour, it should be easy to add an additional flag to WrapperBooster.

`null` parameters

For your convenience, WrapperBooster allows null parameters to the various Wrapper methods. In these cases, null is returned.

Thread safety

To allow multi-threaded applications, the wrapping status is tracked independently for each thread.

Author:: Thorsten Hermes <thermes@i3.informatik.rwth-aachen.de>

Constructor Summary
`WrapperBooster(Wrapper boostedWrapper)` Creates a new WrapperBooster.
`WrapperBooster(Wrapper boostedWrapper, Wrapper preWrapper)` Creates a new WrapperBooster.

Method Summary
`boolean`	`activateWrapping()` Activates wrapping for this thread.
`void`	`clearCaches()` Clears all caches of this WrapperBooster.
`boolean`	`deactivateWrapping()` Deactivates wrapping for this thread.
`protected void`	`finalize()` Unregisters all caches of this WrapperBooster from the CacheManager.
`boolean`	`isWrappingActive()` Checks whether wrapping is activated for this thread.
`void`	`setWrapping(boolean active)` Activates or deactivates wrapping for this thread.
`Attribute`	`wrapAttribute(Attribute a)` Wraps the supplied Attribute.
`Edge`	`wrapEdge(Edge g)` Variant of `Wrapper.wrapGraphEntity(GraphEntity)` to avoid casting.
`EdgeClass`	`wrapEdgeClass(EdgeClass g)` Variant of `Wrapper.wrapGraphEntityClass(GraphEntityClass)` to avoid casting.
`Graph`	`wrapGraph(Graph g)` Variant of `Wrapper.wrapGraphEntity(GraphEntity)` to avoid casting.
`GraphClass`	`wrapGraphClass(GraphClass g)` Variant of `Wrapper.wrapGraphEntityClass(GraphEntityClass)` to avoid casting.
`GraphEntity`	`wrapGraphEntity(GraphEntity g)` Wraps the supplied GraphEntity.
`GraphEntityClass`	`wrapGraphEntityClass(GraphEntityClass g)` Wraps the supplied GraphEntityClass.
`Node`	`wrapNode(Node g)` Variant of `Wrapper.wrapGraphEntity(GraphEntity)` to avoid casting.
`NodeClass`	`wrapNodeClass(NodeClass g)` Variant of `Wrapper.wrapGraphEntityClass(GraphEntityClass)` to avoid casting.
`Relation`	`wrapRelation(Relation g)` Variant of `Wrapper.wrapGraphEntity(GraphEntity)` to avoid casting.
`RelationClass`	`wrapRelationClass(RelationClass g)` Variant of `Wrapper.wrapGraphEntityClass(GraphEntityClass)` to avoid casting.
`RelationEnd`	`wrapRelationEnd(RelationEnd g)` Variant of `Wrapper.wrapGraphEntity(GraphEntity)` to avoid casting.
`RelationEndClass`	`wrapRelationEndClass(RelationEndClass g)` Variant of `Wrapper.wrapGraphEntityClass(GraphEntityClass)` to avoid casting.

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

WrapperBooster

public WrapperBooster(Wrapper boostedWrapper)
               throws DragosException

Creates a new WrapperBooster. Wrapping is activated by default. This WrapperBooster will have no pre-wrapper.

Parameters:: boostedWrapper - the boosted wrapper
Throws:: DragosException - in case of internal errors (especially during cache initialization).

WrapperBooster

public WrapperBooster(Wrapper boostedWrapper,
                      Wrapper preWrapper)
               throws DragosException

Creates a new WrapperBooster. Wrapping is activated by default.

Parameters:: boostedWrapper - the boosted wrapper; preWrapper - the pre-wrapper (may be null)
Throws:: DragosException - in case of internal errors (especially during cache initialization).

Method Detail

activateWrapping

public boolean activateWrapping()

Activates wrapping for this thread.

Returns:: true if wrapping was active before, false otherwise.

deactivateWrapping

public boolean deactivateWrapping()

Deactivates wrapping for this thread.

Returns:: true if wrapping was active before, false otherwise.

setWrapping

public void setWrapping(boolean active)

Activates or deactivates wrapping for this thread. This method is most useful to restore the previous state as returned by activateWrapping() or deactivateWrapping(). It has no effect if the requested wrapping mode is already set.

Parameters:: active - true if wrapping shall be activated, false otherwise.

clearCaches

public void clearCaches()
                 throws DragosException

Clears all caches of this WrapperBooster.

It should be called on an old WrapperBooster after replacing it to free the resources for the caches (which otherwise will not happen until the WrapperBooster is garbage collected).

Throws:: DragosException - DragosException in case of internal errors.

finalize

protected void finalize()
                 throws java.lang.Throwable

Unregisters all caches of this WrapperBooster from the CacheManager.

We can only do this here, not even in an explicit user-invoked method before, because of multi-threading concerns: If another thread already has a reference to a cache, is suspended while the cache is removed, and tries to retrieve an object from it later, it would catch an Exception.

Overrides:: finalize in class java.lang.Object

Throws:: java.lang.Throwable - in case of internal errors.

isWrappingActive

public boolean isWrappingActive()

Checks whether wrapping is activated for this thread.

Returns:: true if wrapping is activated for this thread.

wrapGraphEntity

public GraphEntity wrapGraphEntity(GraphEntity g)
                            throws DragosException

Wraps the supplied GraphEntity. The type of the entity must be left unchanged, e.g. an Edge must only be wrapped in another Edge, not in a Node. In contrast to the general Wrapper interface, this implementation allows null values (for which it will return null).

Specified by:: wrapGraphEntity in interface Wrapper

Parameters:: g - The GraphEntity to wrap, may be null.
Returns:: A GraphEntity of the same type, wrapping the supplied entity in zero or more layers.
Throws:: DragosException - in case of errors during wrapping.