edu.wisc.trace.urcsdk.client.resources
Class ResourceManager

java.lang.Object
  edu.wisc.trace.urcsdk.client.resources.ResourceManager

public class ResourceManager
extends java.lang.Object

ResourceManager takes care of all resource management. It follows very particular algorithms (see below) to maintain a scalable and performant retrieval mechanism.

Standard Retrieval Algorithm:
The Resource Managers resource retrieval algorithm has been changed after the release of URC SDK 3.0 The following is the retrieval algorithm currently implemented: 1. The main principle behind the algorithm is the try-harder concept, meaning, a resource will be parsed if and only if the optimizer decides that the resource manager must try harder in order to obtain the perfect resource. In step1, we take the existing hashmap that stores the resources and check to see if there exists a resource matching the user prefs. If it exists, then go to step2. The key used to search the hashmap is of the form "elementRef valueRef operationRef role". If no resources exist, more resources are parsed, step 5. 2. Using the above key, the list of resources is retrieved. The list may be of size 1 or empty. Two lists are retrieved, one with the valueRef being searched for and one with valueRef = null. If the user does not want resources with valueRef=null to be searched while looking for a particular valueRef, a boolean value of false can be passed as a parameter. (This is not backward compatible). 3. Now the task is passed on to the DefaultOptimizer/(user defined optimizer) to pick the best resource possible. If the optimizer doesn't find the best resource, it can return a null object implying the resource manager should try harder and parse more resources*. The resource manager parses more resource sheets and asks the optimizer to pick the best resource. This keeps going on till the resource manager believes it has parsed all possible resource sheets. If the optimizer believes it doesn't want the resource manager to parse more resource sheets and abort the retrieval, it returns an IResource.EMPTY_RESOURCE object. 4. Once the resource manager has parsed all the possible resources, it sets the isFinal flag to true. This tells the optimizer to pick the next best resource since it cannot parse any more resource sheets. 5. Currenlty, only the resources in the resource directory are parsed. The resource sheets in the resource directory are parsed if their domain, role, language, format and type definitions match to what is being looked for. During the parsing stage, resource sheet keys are stored in a hashmap so the same resource sheet is not parsed more than once. Another hashmap containing the parsed resource sheets is saved. The key for this hashmap is of the form The seperator is a space.valueRef and operationRef can be null. The resources with the same key are stored as a list in the hashmap. Currenlty, no more resource sheets are parsed. But in the future, searching for sheets from other locations - resource server, internet etc will be implemented Note: The new algorithm is backward compatible with the older versions for all cases except if the user wants to restrict retrieval of resources of a null valueRef

Created on: Sep 7, 2004

Modified on: June 14, 2006

Version:

$Revision: 1.21 $

Author:

Hemanth Vijayan, Trace R&D Center

Field Summary

static char

keySeparator Constant value for delimiter for use when constructing resource keys and resource sheet keys.

Constructor Summary

ResourceManager(ResourceDirectory rd)
Creates a new ResourceManager instance.

Method Summary

boolean	addLocalResourceSheet(ResourceSheet rs) addLocalResourceSheet adds a new already instantiated ResourceSheet to this ResourceManager's ResourceDirectory.
int	cacheSize() Returns the number of resources currently in the cache.
void	clearCache() clearCache makes the ResourceManager forget that it has parsed any ResourceSheets in the past.
static java.lang.String	generateResourceKey(ElementRef elementRef, java.lang.String valueRef, java.lang.String opRef, java.lang.String role) Generates the internally-used hash string for storing resources.
static java.lang.String	generateResourceSheetKey(java.lang.String domain, java.lang.String language, java.lang.String role, java.lang.String type, java.lang.String format) Generates the internally-used hash string for storing resource sheets.
IResourceOptimizer	getOptimizer() Returns the currently set optimizer.
IResource	getResource(ElementRef elementRef, java.lang.String valueRef, boolean includeNullValueRef, java.lang.String opRef, java.lang.String role, UserPreferences userPrefs) This method uses the above mentioned retrieval algorithm and returns the best resource possible.
IResource	getResource(ElementRef elementRef, java.lang.String valueRef, java.lang.String opRef, java.lang.String role, UserPreferences userPrefs) This method calls the getResource(elementRef, valueRef, includeNullValueRef, opRef, role, userPrefs) method.
IResource	getResource(java.lang.String language, java.lang.String format, Constants.ResourceRole role, Constants.ResourceType type, ElementRef elementRef, java.lang.String valueRef, java.lang.String opRef, UserPreferences userPrefs) Deprecated. Implemented to preserve backward compatibility.
ResourceDirectory	getResourceDirectory() Returns the top-level ResourceDirectory for this ResourceManager
void	setOptimizer(IResourceOptimizer o) setOptimizer change the currently set optimizer.

Methods inherited from class java.lang.Object

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

Field Detail

keySeparator

public static final char keySeparator

Constant value for delimiter for use when constructing resource keys and resource sheet keys.

See Also:

Constant Field Values

Constructor Detail

ResourceManager

public ResourceManager(ResourceDirectory rd)

Creates a new ResourceManager instance. ResourceManager s require ResourceDirectory s to contain any and all ResourceSheet s that the ResourceManager knows about. If there are no premade ResourceDirectorys available, creating a new one for use in the construction of the ResourceManager is valid. However, no IResources will be available for retrieval until at least one ResourceSheet is added to the ResourceManagers search path via addSearchLocation or addLocalResourceSheet.

Parameters:

rd - a ResourceDirectory value, if no premade ResourceDirectories are available, it is valid to pass: new ResourceDirectory() to the constructor.

Method Detail

generateResourceKey

public static java.lang.String generateResourceKey(ElementRef elementRef,
                                                   java.lang.String valueRef,
                                                   java.lang.String opRef,
                                                   java.lang.String role)

Generates the internally-used hash string for storing resources. The format is:

elementRef+valueRef+opRef+role

Where '+' indicates the delimiter between keys (currently, the delimiter is ' ')

Parameters:

elementRef - an ElementRef object

valueRef - a String object

opRef - a String object

role - a String object

Returns:

a String object

generateResourceSheetKey

public static java.lang.String generateResourceSheetKey(java.lang.String domain,
                                                        java.lang.String language,
                                                        java.lang.String role,
                                                        java.lang.String type,
                                                        java.lang.String format)

Generates the internally-used hash string for storing resource sheets. The format is:

domain+language+role+type+format

Where '+' indicates the delimiter between keys (currently, the delimiter is ' ')

Parameters:

domain - a String object

language - a String object

role - a String object

type - a String object

format - a String object

Returns:

a String object

addLocalResourceSheet

public boolean addLocalResourceSheet(ResourceSheet rs)

addLocalResourceSheet adds a new already instantiated ResourceSheet to this ResourceManager's ResourceDirectory. After this method is called, all future getResource() calls will search this ResourceSheet for a potential IResource.

Parameters:

rs - A ResourceSheet value.

Returns:

A boolean value if the ResourceSheet was added to the ResourceDirectory successfully.

cacheSize

public int cacheSize()

Returns the number of resources currently in the cache.

Returns:

int number of resources in the cache.

clearCache

public void clearCache()

clearCache makes the ResourceManager forget that it has parsed any ResourceSheets in the past. This also clears any cached IResources that have already been retrieved.

getOptimizer

public IResourceOptimizer getOptimizer()

Returns the currently set optimizer.

Returns:

IResourceOptimizer optimizer object

getResource

public IResource getResource(java.lang.String language,
                             java.lang.String format,
                             Constants.ResourceRole role,
                             Constants.ResourceType type,
                             ElementRef elementRef,
                             java.lang.String valueRef,
                             java.lang.String opRef,
                             UserPreferences userPrefs)

Deprecated. Implemented to preserve backward compatibility.

This method calls the getResource(ElementRef elementRef, String valueRef, boolean includeNullValueRef, String opRef, String role, UserPreferences userPrefs) method. where includeNullValueRef is set to false

Parameters:

language - a String object

format - a String object

role - a Role object

type - a String object

elementRef - an ElementRef object

valueRef - a String object

opRef - a String object

userPrefs - a UserPreferences object

Returns:

an IResource object (of type EmptyResource, if no valid resource is found)

getResource

public IResource getResource(ElementRef elementRef,
                             java.lang.String valueRef,
                             boolean includeNullValueRef,
                             java.lang.String opRef,
                             java.lang.String role,
                             UserPreferences userPrefs)

This method uses the above mentioned retrieval algorithm and returns the best resource possible. If nothing is found, an empty resource is returned.

Parameters:

elementRef -

valueRef -

includeNullValueRef -

opRef -

role -

userPrefs -

Returns:

best available resource

getResource

public IResource getResource(ElementRef elementRef,
                             java.lang.String valueRef,
                             java.lang.String opRef,
                             java.lang.String role,
                             UserPreferences userPrefs)

This method calls the getResource(elementRef, valueRef, includeNullValueRef, opRef, role, userPrefs) method. It passes false for the boolean includeNullValueRef.

Parameters:

elementRef -

valueRef -

opRef -

role -

userPrefs -

Returns:

best available resource

getResourceDirectory

public ResourceDirectory getResourceDirectory()

Returns the top-level ResourceDirectory for this ResourceManager

Returns:

a ResourceDirectory object.

setOptimizer

public void setOptimizer(IResourceOptimizer o)

setOptimizer change the currently set optimizer.

Parameters:

o - an IResourceOptimizer value