com.bigdata.relation.locator
Class DefaultResourceLocator<T extends ILocatableResource>

java.lang.Object
  com.bigdata.relation.locator.DefaultResourceLocator<T>

Type Parameters:

T - The generic type of the [R]elation.

All Implemented Interfaces:

IResourceLocator<T>

public class DefaultResourceLocator<T extends ILocatableResource>
extends Object
implements IResourceLocator<T>

Generic implementation relies on a ctor for the resource with the following method signature:

 public NAME ( IIndexManager indexManager, String namespace, Long timestamp, Properties properties )
 

A relation is located using the IIndexStore.getGlobalRowStore(long) and materialized by supplying an IIndexManager that will be able to resolve the indices for the relation's view. Several different contexts are handled:

IBigdataFederation

The IRelation will be resolved using the IIndexStore.getGlobalRowStore(long) and the IBigdataFederation as its IIndexManager. The makes access to a remote and potentially distributed IIndex transparent to the IRelation. However, it is NOT possible to resolve local resources on other JVMs - only scale-out indices registered against the IBigdataFederation.

Journal

The IRelation will be resolved using the Journal.getGlobalRowStore(long) and will use the local index objects directly.

AbstractTask

If the index is local and monolithic then you can declare the index to the AbstractTask and override the locator to use AbstractTask.getJournal() as its index manager. This will give you access to the local index object from within the concurrency control mechanism

TemporaryStore

When used by itself, this is just like a Journal. However, TemporaryStores are also used to provide local resources for more efficient data storage for a variety of purposes. When used in this manner, you must explicitly notify the locator of the existence of the TemporaryStore in order to be able to resolve IRelations on the TemporaryStore. It is prudent to use a prefix for such local resources that guarentees uniqueness, e.g., an UUID

Version:

$Id: DefaultResourceLocator.java 6041 2012-02-20 20:46:45Z thompsonbry $

Author:

Bryan Thompson

Field Summary

protected static int	DEFAULT_CACHE_CAPACITY The default #of recently located resources whose hard references will be retained by the LRUCache.
protected static long	DEFAULT_CACHE_TIMEOUT The default timeout for stale entries in milliseconds.
protected IIndexManager	indexManager
protected static org.apache.log4j.Logger	log

Constructor Summary

DefaultResourceLocator(IIndexManager indexManager, IResourceLocator<T> delegate)
Ctor uses DEFAULT_CACHE_CAPACITY and DEFAULT_CACHE_TIMEOUT.

DefaultResourceLocator(IIndexManager indexManager, IResourceLocator<T> delegate, int cacheCapacity, long cacheTimeout)

Method Summary

void	add(IIndexManager indexManager) Causes the IIndexManager to be tested when attempting to resolve a resource identifiers.
void	discard(ILocatableResource<T> instance) Resources that hold hard references to local index objects MUST be discarded during abort processing.
T	locate(String namespace, long timestamp) Locate.
protected Properties	locateResource(String namespace, long timestamp, AtomicReference<IIndexManager> foundOn) Note: Caller is synchronized for this namespace.
protected Properties	locateResourceOn(IIndexManager indexManager, String namespace, long timestamp) Return the Properties that will be used to configure the IRelation instance.
protected T	newInstance(Class<? extends T> cls, IIndexManager indexManager, NT nt, Properties properties) Create a new view of the relation.
T	putInstance(T instance) Places the instance into the cache iff there is no existing instance in the cache for the same resource and timestamp.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final transient org.apache.log4j.Logger log

indexManager

protected final transient IIndexManager indexManager

DEFAULT_CACHE_CAPACITY

protected static final transient int DEFAULT_CACHE_CAPACITY

The default #of recently located resources whose hard references will be retained by the LRUCache.

See Also:

Constant Field Values

DEFAULT_CACHE_TIMEOUT

protected static final transient long DEFAULT_CACHE_TIMEOUT

The default timeout for stale entries in milliseconds.

See Also:

Constant Field Values

Constructor Detail

DefaultResourceLocator

public DefaultResourceLocator(IIndexManager indexManager,
                              IResourceLocator<T> delegate)

Ctor uses DEFAULT_CACHE_CAPACITY and DEFAULT_CACHE_TIMEOUT.

Parameters:

indexManager -

delegate - Optional IResourceLocator to which unanswered requests are then delegated.

DefaultResourceLocator

public DefaultResourceLocator(IIndexManager indexManager,
                              IResourceLocator<T> delegate,
                              int cacheCapacity,
                              long cacheTimeout)

Parameters:

indexManager -

delegate - Optional IResourceLocator to which unanswered requests are then delegated.

cacheCapacity - The capacity of the internal weak value cache.

cacheTimeout - The timeout in milliseconds for stale entries in that cache.

Method Detail

locate

public T locate(String namespace,
                long timestamp)

Description copied from interface: IResourceLocator

Locate.

Specified by:

locate in interface IResourceLocator<T extends ILocatableResource>

Parameters:

namespace - The resource namespace.

timestamp - The timestamp for the view.

Returns:

A view of the resource iff it exists (specifically, if the declaration for the resource can be resolved) -or- null if the resource declaration could not be resolved.

locateResource

protected Properties locateResource(String namespace,
                                    long timestamp,
                                    AtomicReference<IIndexManager> foundOn)

Note: Caller is synchronized for this namespace.

Parameters:

namespace - The namespace for the resource.

timestamp -

foundOn - Used to pass back the IIndexManager on which the resource was found as a side-effect.

Returns:

The properties for that resource.

locateResourceOn

protected Properties locateResourceOn(IIndexManager indexManager,
                                      String namespace,
                                      long timestamp)

Return the Properties that will be used to configure the IRelation instance. The RelationSchema.CLASS property MUST be defined and specified the runtime class that will be instantiated.

Note: A null return is an indication that the resource was NOT FOUND on this IIndexManager and the caller SHOULD try another IIndexManager.

Parameters:

indexManager -

namespace - The resource identifier - this is the primary key.

timestamp - The timestamp of the resource view.

Returns:

The Properties iff there is a logical row for the given namespace.

newInstance

protected T newInstance(Class<? extends T> cls,
                        IIndexManager indexManager,
                        NT nt,
                        Properties properties)

Create a new view of the relation.

Parameters:

indexManager - The IIndexManager that will be used to resolve the named indices for the relation.

namespace - The namespace for the relation.

timestamp - The timestamp for the view of the relation.

properties - Configuration properties for the relation.

Returns:

A new instance of the identified resource.

putInstance

public T putInstance(T instance)

Places the instance into the cache iff there is no existing instance in the cache for the same resource and timestamp.

Note: This is done automatically by AbstractResource.

Parameters:

instance - The instance.

discard

public void discard(ILocatableResource<T> instance)

Description copied from interface: IResourceLocator

Resources that hold hard references to local index objects MUST be discarded during abort processing. Otherwise the same resource objects will be returned from the cache and buffered writes on the indices for those relations (if they are local index objects) will still be visible, thus defeating the abort semantics.

Specified by:

discard in interface IResourceLocator<T extends ILocatableResource>

add

public void add(IIndexManager indexManager)

Causes the IIndexManager to be tested when attempting to resolve a resource identifiers. The IIndexManager will be automatically cleared from the set of IIndexManagers to be tested if its reference is cleared by the JVM. If it becomes closed asynchronously then a warning will be logged until its reference is cleared.

Note: The default IIndexManager specified to the ctor normally ensures that the global namespace is consistent (it is not possible to have two indices or ILocatableResources with the same name). When you add additional IIndexManagers, the opportunity for an inconsistent unified namespace is introduced. You can protect yourself by ensuring that resources located on TemporaryStores and the like are always created with a unique prefix, e.g., the UUID of the TemporaryStore itself or a UUID for each container that is allocated on the TemporaryStore.

Parameters:

indexManager - Typically a TemporaryStore or Journal containing local resources.

See Also:

#locateResource(String)