Package edu.wisc.trace.urcsdk.client.resources

Provides classes for dealing with Resources and their respective XML documents.

See:
Description

Interface Summary

IResource	IResource is the interface used for creating new resource types from scratch.
IResourceOptimizer	IResourceOptimizer is an interface for creating resource retrieval optimizers.

Class Summary

AbstractResource	AbstractResource is the abstract implementation of IResource that all of the SDK resource types extend from.
AResourceDescription	AResourceDescription is the object representation of an Atomic resource as defined by the specs and described in Resource Sheet XML documents.
DefaultOptimizer	DefaultOptimizer is the default implementation of the IResourceOptimizer.
EmptyResource	EmptyResource is a dummy resource type for cases where a resource is required, but no valid resources could be found.
FileRetriever	FileRetriever is a utility class that can retrieve files from multiple sources and return URC compliant resources.
ImageResource	ImageResource is the type of resource that applies to images.
ListResource	ListResource represents a special type of resource where more than one resource applies equally to an retrieval.
ResourceContent	ResourceContent provides a way to extract information about the literal value of a resource on a finer level.
ResourceDirectory	ResourceDirectory is the programmatic version of the XML <ResourceDirectory> element.
ResourceManager	ResourceManager takes care of all resource management.
ResourceServiceDescription	ResourceServiceDescription represents the XML for the resource service description found in the resource directory for a target.
ResourceSheet	ResourceSheet is the object form of a Resource Sheet.
ResourceSheetDescription	ResourceSheetDescription is the object form of the XML <ResourceSheet> element found in the TargetDirectory.
ResourceUseContext	ResourceUseContext is the class representation of the <useContext> element within a resource description.
TextResource	TextResource is the IResource implementation for representing Text-based resources in any language.

Package edu.wisc.trace.urcsdk.client.resources Description

Provides classes for dealing with Resources and their respective XML documents.

Classes within this package are implemented or overridden to implement new Resource types and deal with the retrieval of those resources.

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