i3.dragos.gm.core.filter
Class FilteringGraphPool

java.lang.Object
  i3.dragos.gm.core.filter.FilteringGraphPool

All Implemented Interfaces:

GraphPool, MetaAttributable

public class FilteringGraphPool
extends java.lang.Object
implements GraphPool

A GraphPool implementation that hides top level graphs whose names start with a specific prefix.

All methods from the GraphPool interface are modified to not allow the creation and removal of top level graphs with reserved names and to filter out these graphs from the results of get* methods.

For working directly with the underlying unfiltered graph pool the method turnFilteringOff() is provided. The method turnFilteringOn() reactivates filtering mechanism. Both methods affect both the graph pool and the associated schema instance.

Author:

Thomas Lettow <lettow@i3.informatik.rwth-aachen.de>, Thorsten Hermes <thermes@i3.informatik.rwth-aachen.de>

Constructor Summary

FilteringGraphPool(GraphPool pool, java.lang.String prefix)
Creates a new FilteringGraphPool.

Method Summary

void	clear(boolean alsoClearSchema) Removes every graph entity from this graph pool, and possibly every class declaration from the schema.
void	close() Closes the graph pool and frees all temporary resources used by it.
Graph	createTopLevelGraph(java.lang.String name, GraphClass type) Creates a new (top-level) graph with the given name.
boolean	existsTopLevelGraph(java.lang.String name) Returns true if a graph identified by the name is stored in the pool and false otherwise.
java.util.Collection<? extends GraphEntity>	getAllInstances(GraphEntityClass id) Returns all instances of a GraphEntityClass contained in the pool.
java.util.Map<java.lang.String,java.io.Serializable>	getAllMetaAttributes() Returns a map containing all currently set meta-attribute key-value pairs.
java.util.Collection<? extends Graph>	getAllTopLevelGraphs() Returns all top-level graphs (those which have no parent graph) stored in this graph pool.
DataSourceURL	getDataSourceURL() Returns the URL to the data source of this graph pool.
boolean	getForceExistenceCheckOnRead() Tells wether the existence of any entity or entity class is checked before performing a reading operation.
GraphEntity	getGraphEntityByInternalIdentifier(java.io.Serializable identifier) Retrieves a GraphEntity by its internal identifier.
DefaultGraphPoolChecker	getGraphPoolChecker() Returns the GraphPoolChecker of the wrapped graph pool.
java.io.Serializable	getMetaAttribute(java.lang.String key) Returns the current value of a meta-attribute.
FilteringSchema	getSchema() Returns the schema used for all elements in this graph pool.
Graph	getTopLevelGraphByName(java.lang.String name) Returns the top-level graph identified by the specified name.
GraphPool	getWrappedGraphPool() Returns the wrapped graph pool, null if none.
Wrapper	getWrapper() Returns the Wrapper currently used by the GraphPool.
void	init() Initializes a graph pool.
boolean	isFilteringOn() Returns true if filtering mechanism is turned on.
boolean	isMetaAttributeKeyReserved(java.lang.String key) Checks whether a meta-attribute key is reserved for internal use.
boolean	isMetaAttributeSet(java.lang.String key) Checks whether a meta-attribute is set.
void	open() Prepares the graph pool for normal operation.
void	removeAllAttributeInstances(Attribute attribute) Removes every instance of an attribute from the pool.
void	removeAllInstances(GraphEntityClass id) Removes every instance of a GraphEntityClass from the pool.
void	removeTopLevelGraph(Graph graph) Deletes a top-level graph.
void	reorganizePool() Reorganizes the entire graph pool.
void	setForceExistenceCheckOnRead(boolean b) Sets wether the existence of any entity or entity class is checked before performing a reading operation.
void	setMetaAttribute(java.lang.String key, java.io.Serializable value) Sets a meta-attribute.
void	setWrapper(Wrapper w) Sets the Wrapper to be used by the GraphPool.
void	turnFilteringOff() Deactivates filtering mechanism both of the schema and of the associated graph pool instance.
void	turnFilteringOn() Activates filtering mechanism both of the schema and of the associated graph pool instance.
void	unsetMetaAttribute(java.lang.String key) Removes a meta-attribute.

Methods inherited from class java.lang.Object

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

Constructor Detail

FilteringGraphPool

public FilteringGraphPool(GraphPool pool,
                          java.lang.String prefix)
                   throws DragosException

Creates a new FilteringGraphPool.

Parameters:

pool - the wrapped GraphPool instance.

prefix - the prefix that determines which top level graphs are filtered out.

Throws:

DragosException - if something went wrong

Method Detail

getWrappedGraphPool

public GraphPool getWrappedGraphPool()

Returns the wrapped graph pool, null if none.

If there is more than one instance of any sub-interface or implementing class in the wrapper chain, partial unwrapping (needed mostly to access newly defined methods) may not work as expected. It is up to the application to ensure that no wrapper is included more than once.

This method must work even when the GraphPool is closed.

Specified by:

getWrappedGraphPool in interface GraphPool

Returns:

the wrapped GraphPool, null if none.

See Also:

GraphPoolFactory.unwrapGraphPoolTill(GraphPool, ExtensionDescriptor)

getDataSourceURL

public DataSourceURL getDataSourceURL()

Returns the URL to the data source of this graph pool. The returned value can not be null.

This method must work even when the GraphPool is closed.

Specified by:

getDataSourceURL in interface GraphPool

Returns:

the URL to the data source of this graph pool.

getSchema

public FilteringSchema getSchema()
                          throws DragosException

Returns the schema used for all elements in this graph pool.

This method must work even when the GraphPool is closed.

Specified by:

getSchema in interface GraphPool

Returns:

schema used for all elements in this graph pool.

Throws:

DragosException - if something went wrong.

init

public void init()
          throws GraphPoolException

Initializes a graph pool. Implementations have to comply to the this contract:

• If this pool wraps another pool, the wrapped pool's init method must be called first
• subsequent calls to this method on already initialized graph pool may have no effect

The application has to ensure that

• this method is only called on opened graph pools
• a transaction is active on the DataSource and accessible via the TransactionManagerFactory
• the method is called at least once before the first access to the graph pool after GraphPool.open()

Specified by:

init in interface GraphPool

Throws:

GraphPoolException - if something went wrong.

createTopLevelGraph

public Graph createTopLevelGraph(java.lang.String name,
                                 GraphClass type)
                          throws EntityNotFoundException,
                                 DragosException,
                                 java.lang.IllegalArgumentException,
                                 EntityAlreadyExistsException

Creates a new (top-level) graph with the given name.

Behaves exactly like GraphPool.createTopLevelGraph(String, GraphClass) except that name is not allowed to start with the reserved prefix.

Specified by:

createTopLevelGraph in interface GraphPool

Parameters:

name - The name of the graph.

type - The graphs type.

Returns:

A new graph of the specified name.

Throws:

java.lang.IllegalArgumentException - if name is null or starts with reserved prefix.

EntityNotFoundException - if the type could not be found.

EntityAlreadyExistsException - if a graph with this name already exists.

GraphEntityInstantiationException - if type is declared as an abstract class.

DragosException - if something went wrong.

existsTopLevelGraph

public boolean existsTopLevelGraph(java.lang.String name)
                            throws DragosException

Returns true if a graph identified by the name is stored in the pool and false otherwise.

Behaves exactly like GraphPool.existsTopLevelGraph(String) except that name is not allowed to start with the reserved prefix.

Specified by:

existsTopLevelGraph in interface GraphPool

Parameters:

name - The name of the graph.

Returns:

true if a graph identified by the name is stored in the pool and false otherwise.

Throws:

java.lang.IllegalArgumentException - if name starts with reserved prefix.

DragosException - if something went wrong.

removeTopLevelGraph

public void removeTopLevelGraph(Graph graph)
                         throws EntityNotFoundException,
                                DragosException

Deletes a top-level graph.

See Graph.removeGraphEntity(GraphEntity) for a detailed description on the deletion process.

Any non-top-level graphs should be deleted by calling Graph.removeGraphEntity(GraphEntity) on their parent graph instead.

Behaves exactly like GraphPool.existsTopLevelGraph(String) except that an EntityNotFoundException is thrown if the graph entity with the given internal identifier is filtered out.

Specified by:

removeTopLevelGraph in interface GraphPool

Parameters:

graph - The graph.

Throws:

EntityNotFoundException - if the graph is not a top-level graph in this GraphPool.

DragosException - if something went wrong.

getAllTopLevelGraphs

public java.util.Collection<? extends Graph> getAllTopLevelGraphs()
                                                           throws DragosException

Returns all top-level graphs (those which have no parent graph) stored in this graph pool. The elements in the collection are of type Graph.

Behaves exactly like GraphPool.getAllTopLevelGraphs() except that all top level graphs whose names start with the specified prefix are filtered out.

Specified by:

getAllTopLevelGraphs in interface GraphPool

Returns:

A Collection of Graphs (may be empty, but never null).

Throws:

DragosException - in case of internal errors.

getTopLevelGraphByName

public Graph getTopLevelGraphByName(java.lang.String name)
                             throws EntityNotFoundException,
                                    DragosException,
                                    java.lang.IllegalArgumentException

Returns the top-level graph identified by the specified name.

Behaves exactly like GraphPool.getTopLevelGraphByName(String) except that name is not allowed to start with the reserved prefix.

Specified by:

getTopLevelGraphByName in interface GraphPool

Parameters:

name - The name of the graph.

Returns:

The graph associated with the name.

Throws:

java.lang.IllegalArgumentException - if name starts with reserved prefix.

EntityNotFoundException - if the graph does not exist.

DragosException - if something else went wrong.

getGraphEntityByInternalIdentifier

public GraphEntity getGraphEntityByInternalIdentifier(java.io.Serializable identifier)
                                               throws EntityNotFoundException,
                                                      DragosException

Retrieves a GraphEntity by its internal identifier.

Behaves exactly like GraphPool.getGraphEntityByInternalIdentifier(Serializable) except that an EntityNotFoundException is thrown if the graph entity with the given internal identifier is filtered out.

Specified by:

getGraphEntityByInternalIdentifier in interface GraphPool

Parameters:

identifier - The internal identifier.

Returns:

The requested GraphEntity (subclass).

Throws:

EntityNotFoundException - if the graph entity does not exist.

DragosException - if something else went wrong.

clear

public void clear(boolean alsoClearSchema)
           throws DragosException

Removes every graph entity from this graph pool, and possibly every class declaration from the schema. This method does not require implementations to remove all elements one-by-one from the underlying datasource. Only the firing of an according GraphPoolEvent is required.

Attention: no filtering of reserved entities.

TODO: filtered clearing of schema is not possible at the moment

Specified by:

clear in interface GraphPool

Parameters:

alsoClearSchema - Whether Schema.clear() should be called after successful removal of all entities in the pool.

Throws:

DragosException - if something went wrong.

getAllInstances

public java.util.Collection<? extends GraphEntity> getAllInstances(GraphEntityClass id)
                                                            throws EntityNotFoundException,
                                                                   DragosException

Returns all instances of a GraphEntityClass contained in the pool.

Behaves exactly like GraphPool.getAllInstances(GraphEntityClass) except that an EntityNotFoundException is thrown if the given graph entity class is filtered out of the schema.

Specified by:

getAllInstances in interface GraphPool

Parameters:

id - The class whose instances are to be returned.

Returns:

All instances of a GraphEntityClass contained in the pool.

Throws:

EntityNotFoundException - if the class was not found in the schema.

DragosException - if something went wrong.

removeAllInstances

public void removeAllInstances(GraphEntityClass id)
                        throws EntityNotFoundException,
                               DragosException

Removes every instance of a GraphEntityClass from the pool.

Deletion must follow the general procedure for deletion of graph entities, described at Graph.removeGraphEntity(GraphEntity).

The easiest way to ensure this is to proceed as follows for every graph entity in this pool:

• For top-level graphs call GraphPool.removeTopLevelGraph(Graph).
• For all other graph entities call Graph.removeGraphEntity(GraphEntity) on their parent graph.

Implementation notice: Some instances might already be deleted due to cascading removal of entities processed before, so take care when iterating through the instances.

Behaves exactly like GraphPool.removeAllInstances(GraphEntityClass) except that an EntityNotFoundException is thrown if the given graph entity class is filtered out of the schema.

Specified by:

removeAllInstances in interface GraphPool

Parameters:

id - The class whose instances are to be deleted.

Throws:

EntityNotFoundException - if the class was not found in the schema.

DragosException - if something went wrong.

removeAllAttributeInstances

public void removeAllAttributeInstances(Attribute attribute)
                                 throws EntityNotFoundException,
                                        DragosException

Removes every instance of an attribute from the pool. This includes occurences marked as invalid (if such data is not discarded immediately upon invalidation) to avoid zombies.

Behaves exactly like GraphPool.removeAllInstances(GraphEntityClass) except that an EntityNotFoundException is thrown if the graph entity class the attribute is defined for is filtered out of the schema.

Specified by:

removeAllAttributeInstances in interface GraphPool

Parameters:

attribute - The attribute whose instances are to be deleted.

Throws:

EntityNotFoundException - if the attribute definition was not found in the schema.

DragosException - if something went wrong.

reorganizePool

public void reorganizePool()
                    throws EntityInUseException,
                           DragosException

Reorganizes the entire graph pool. This includes

• Removal of all kinds of unused informations
• Compaction of informations
• Release of all existing locks (due to crashes)
• ...

Any information that is used by applications to access any kind of information externally visible (like internal identifiers) will not be modified.

Caution: This method should only be used by privileged application modules because exclusive access to the graph pool is required in general.

Specified by:

reorganizePool in interface GraphPool

Throws:

EntityInUseException - if the graph use by some other component.

DragosException - if something went wrong.

close

public void close()
           throws GraphPoolException

Closes the graph pool and frees all temporary resources used by it. The data stored in the graph pool is not deleted! If the pool is already closed, a call to this method will have no effect.

This method must work even when the GraphPool is closed.

Specified by:

close in interface GraphPool

Throws:

GraphPoolException - if something went wrong.

See Also:

GraphPool.open()

open

public void open()
          throws GraphPoolException

Prepares the graph pool for normal operation. If the pool is already opened, a call to this method will have no effect.

This method must work even when the GraphPool is closed.

Specified by:

open in interface GraphPool

Throws:

GraphPoolException - if something went wrong.

See Also:

GraphPool.close()

setForceExistenceCheckOnRead

public void setForceExistenceCheckOnRead(boolean b)

Sets wether the existence of any entity or entity class is checked before performing a reading operation. See the "Consistency" section in the documentation for details.

Specified by:

setForceExistenceCheckOnRead in interface GraphPool

Parameters:

b - The new value of the flag.

getForceExistenceCheckOnRead

public boolean getForceExistenceCheckOnRead()

Tells wether the existence of any entity or entity class is checked before performing a reading operation. See the "Consistency" section in the documentation for details.

Specified by:

getForceExistenceCheckOnRead in interface GraphPool

Returns:

The value of the flag.

getWrapper

public Wrapper getWrapper()

Returns the Wrapper currently used by the GraphPool. Since any GraphPool is initialized with a NullWrapper upon creation, and GraphPool.setWrapper(Wrapper) does not allow a null argument, the returned value is guaranteed not to be null.

The Wrapper itself must not be modified after it has been set, the wrapping mechanism should be immutable! Rationale: We want to allow the caching of wrapped entities, and changes directly to the Wrapper will not be noticed by the GraphPool, meaning entities wrapped according to the old rules may remain in the caches and still be returned! To change the Wrapper, e.g. add a new layer to a MultiWrapper, create a completely new Wrapper and set it using this method. The GraphPool will take this as a sign to discard not only the old Wrapper, but also any caches associated with it!

This method must work even when the GraphPool is closed.

Specified by:

getWrapper in interface GraphPool

Returns:

the Wrapper currently used by the GraphPool.

See Also:

Wrapper

setWrapper

public void setWrapper(Wrapper w)
                throws DragosException

Sets the Wrapper to be used by the GraphPool. If you do not need any additional functionality, use the NullWrapper (which is the default Wrapper set upon GraphPool creation)

This method must work even when the GraphPool is closed.

Specified by:

setWrapper in interface GraphPool

Parameters:

w - the Wrapper to be used by the GraphPool (must not be null).

Throws:

DragosException - if something went wrong.

See Also:

Wrapper

getGraphPoolChecker

public DefaultGraphPoolChecker getGraphPoolChecker()

Returns the GraphPoolChecker of the wrapped graph pool.

Specified by:

getGraphPoolChecker in interface GraphPool

Returns:

the GraphPoolChecker of the wrapped graph pool.

See Also:

GraphPool.getGraphPoolChecker()

getAllMetaAttributes

public java.util.Map<java.lang.String,java.io.Serializable> getAllMetaAttributes()
                                                                          throws DragosException

Returns a map containing all currently set meta-attribute key-value pairs.

Specified by:

getAllMetaAttributes in interface MetaAttributable

Returns:

A Map containing key-value pairs for all set meta-attributes.

Throws:

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

getMetaAttribute

public java.io.Serializable getMetaAttribute(java.lang.String key)
                                      throws EntityNotFoundException,
                                             DragosException

Returns the current value of a meta-attribute.

Specified by:

getMetaAttribute in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

Returns:

The current value of this meta-attribute.

Throws:

EntityNotFoundException - if no meta-attribute with that name exists.

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

isMetaAttributeKeyReserved

public boolean isMetaAttributeKeyReserved(java.lang.String key)
                                   throws DragosException

Checks whether a meta-attribute key is reserved for internal use.

Specified by:

isMetaAttributeKeyReserved in interface MetaAttributable

Parameters:

key - The key in question.

Returns:

true if this meta-attribute key is reserved, false otherwise.

Throws:

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

isMetaAttributeSet

public boolean isMetaAttributeSet(java.lang.String key)
                           throws EntityNotFoundException,
                                  DragosException

Checks whether a meta-attribute is set. Meta-attributes with reserved keys are not treated in any special way by this method.

Specified by:

isMetaAttributeSet in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

Returns:

true if the meta-attribute is set, false otherwise.

Throws:

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

EntityNotFoundException

setMetaAttribute

public void setMetaAttribute(java.lang.String key,
                             java.io.Serializable value)
                      throws EntityInUseException,
                             DragosException

Sets a meta-attribute. Any old value will be overwritten.

Specified by:

setMetaAttribute in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

value - The (new) value of this meta-attribute.

Throws:

EntityInUseException - if a key name is reserved for internal use.

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

unsetMetaAttribute

public void unsetMetaAttribute(java.lang.String key)
                        throws EntityInUseException,
                               DragosException

Removes a meta-attribute. If no value was set before, this method has no effect.

Specified by:

unsetMetaAttribute in interface MetaAttributable

Parameters:

key - The key that identifies the meta attribute.

Throws:

EntityInUseException - if a key name is reserved for internal use.

DragosException - if this object is no longer in its GraphPool/Schema, or something else went wrong.

isFilteringOn

public boolean isFilteringOn()

Returns true if filtering mechanism is turned on.

Returns:

true if filtering mechanism is turned on.

turnFilteringOn

public void turnFilteringOn()

Activates filtering mechanism both of the schema and of the associated graph pool instance.

turnFilteringOff

public void turnFilteringOff()

Deactivates filtering mechanism both of the schema and of the associated graph pool instance.