org.eclipse.datatools.connectivity.oda.util
Class ResourceIdentifiers

java.lang.Object
  extended by org.eclipse.datatools.connectivity.oda.util.ResourceIdentifiers

public class ResourceIdentifiers
extends java.lang.Object

Represents the resource identifiers of an ODA consumer application. An ODA consumer application may optionally specify its resource identifiers in an instance, and pass it to an ODA runtime driver in an application context map. An application context map is normally passed through the ODA runtime interfaces' setAppContext method(s). Its support and usage by an individual ODA runtime driver is optional and implementation-dependent.

Since:
3.2 (DTP 1.7)

Nested Class Summary
 class ResourceIdentifiers.URILocator
          The default locator of a resource URI relative to a specified base URI.
 
Field Summary
static java.lang.String ODA_APP_CONTEXT_KEY_CONSUMER_RESOURCE_IDS
          A pre-defined key to associate an instance of ResourceIdentifiers in an application context map.
 
Constructor Summary
ResourceIdentifiers()
           
 
Method Summary
static java.net.URI encodeToURI(java.lang.String filePath)
          Encode non-US-ASCII characters in specified file path into an URI.
static ResourceIdentifiers get(java.lang.Object appContext)
          A convenience method to obtain the ResourceIdentifiers instance stored in the specified application context Map with the pre-defined key.
 java.net.URI getApplResourceBaseURI()
          Returns the base URI of general purpose resources of an ODA consumer application.
static java.net.URI getApplResourceBaseURI(java.lang.Object instance)
          A convenience method for a client to invoke the method getApplResourceBaseURI() on the specified ResourceIdentifiers instance.
 ResourceIdentifiers.URILocator getApplResourceURILocator()
          Returns the URI Locator registered by an ODA consumer application for its application resources.
 java.net.URI getDesignResourceBaseURI()
          Returns the base URI of the design resources of an ODA consumer application.
static java.net.URI getDesignResourceBaseURI(java.lang.Object instance)
          A convenience method for a client to invoke the method getDesignResourceBaseURI() on the specified ResourceIdentifiers instance.
 ResourceIdentifiers.URILocator getDesignResourceURILocator()
          Returns the URI Locator registered by an ODA consumer application for its design resources.
 void registerApplResourceURILocator(ResourceIdentifiers.URILocator uriLocator)
          Registers an URILocator defined by an ODA consumer application for its application resources.
 void registerDesignResourceURILocator(ResourceIdentifiers.URILocator uriLocator)
          Registers a URILocator defined by an ODA consumer application for its design resources.
static java.net.URI resolveApplResource(java.lang.Object instance, java.net.URI uri)
          A convenience method for a client to invoke the method resolveApplResource(URI) on the specified ResourceIdentifiers instance.
 java.net.URI resolveApplResource(java.net.URI uri)
          Resolves the specified URI against the base URI of an ODA consumer application's general purpose resources.
static java.net.URI resolveDesignResource(java.lang.Object instance, java.net.URI uri)
          A convenience method for a client to invoke the method resolveDesignResource(URI) on the specified ResourceIdentifiers instance.
 java.net.URI resolveDesignResource(java.net.URI uri)
          Resolves the specified URI against the base URI of an ODA consumer application's design resources.
 java.net.URI resolveResourceLocation(java.lang.String resourcePath)
          EXPERIMENTAL Converts and resolves the specified resource location path to a URI, based on the registered resource URILocator and its base URI.
 void setApplResourceBaseURI(java.net.URI baseURI)
          Specifies the base URI of general purpose resources of an ODA consumer application.
 void setDesignResourceBaseURI(java.net.URI baseURI)
          Specifies the base URI of the design resources of an ODA consumer application.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ODA_APP_CONTEXT_KEY_CONSUMER_RESOURCE_IDS

public static final java.lang.String ODA_APP_CONTEXT_KEY_CONSUMER_RESOURCE_IDS
A pre-defined key to associate an instance of ResourceIdentifiers in an application context map.

See Also:
Constant Field Values
Constructor Detail

ResourceIdentifiers

public ResourceIdentifiers()
Method Detail

get

public static ResourceIdentifiers get(java.lang.Object appContext)
A convenience method to obtain the ResourceIdentifiers instance stored in the specified application context Map with the pre-defined key.

Parameters:
appContext - an application context Map
Returns:
a ResourceIdentifiers instance, normally set by an ODA consumer application; may be null if none is available
Since:
3.3.2 (DTP 1.9)

resolveApplResource

public static java.net.URI resolveApplResource(java.lang.Object instance,
                                               java.net.URI uri)
A convenience method for a client to invoke the method resolveApplResource(URI) on the specified ResourceIdentifiers instance. This supports the use case where the class of the specified instance is not accessible by this class loader(s).

Parameters:
instance - an instance of ResourceIdentifiers
uri - the URI to be resolved against the application resource base URI
Returns:
the resulting URI
Since:
3.3.3 (DTP 1.9.2)
See Also:
resolveApplResource(URI)

getApplResourceBaseURI

public static java.net.URI getApplResourceBaseURI(java.lang.Object instance)
A convenience method for a client to invoke the method getApplResourceBaseURI() on the specified ResourceIdentifiers instance. This supports the use case where the class of the specified instance is not accessible by this class loader(s).

Parameters:
instance - an instance of ResourceIdentifiers
Returns:
the resulting URI
Since:
3.3.3 (DTP 1.9.2)
See Also:
#getApplResourceBaseURI()}

resolveApplResource

public java.net.URI resolveApplResource(java.net.URI uri)
Resolves the specified URI against the base URI of an ODA consumer application's general purpose resources. It uses the application resource URI Locator registered by an ODA consumer application to resolve an application resource URI.

Parameters:
uri - the URI to be resolved against the application resource base URI
Returns:
the resulting URI
Since:
DTP 1.7

getApplResourceBaseURI

public java.net.URI getApplResourceBaseURI()
Returns the base URI of general purpose resources of an ODA consumer application. The returned URI is application-dependent, and may be not well defined. In such case, the client should use resolveApplResource(URI) or get the URI locator in getApplResourceURILocator() to resolve a relative URI reference.

Returns:
base URI; may be null
See Also:
resolveApplResource(URI), getApplResourceURILocator()

setApplResourceBaseURI

public void setApplResourceBaseURI(java.net.URI baseURI)
Specifies the base URI of general purpose resources of an ODA consumer application. It registers an ResourceIdentifiers.URILocator that can be used by a client to resolve a resource URI against the specified baseURI. Any previously registered application resource URILocator and its base URI is replaced.

Parameters:
baseURI - base URI; may be null
See Also:
registerApplResourceURILocator(URILocator)

getApplResourceURILocator

public ResourceIdentifiers.URILocator getApplResourceURILocator()
Returns the URI Locator registered by an ODA consumer application for its application resources. A custom ODA designer may use the URI locator to resolve an application resource URI.

Returns:
application resource URI locator; may be null if none is available
See Also:
getApplResourceBaseURI()

registerApplResourceURILocator

public void registerApplResourceURILocator(ResourceIdentifiers.URILocator uriLocator)
Registers an URILocator defined by an ODA consumer application for its application resources. Replaces any previously registered application resources URILocator and its base URI.

Parameters:
uriLocator - an application resource URI locator
See Also:
setApplResourceBaseURI(URI)

resolveDesignResource

public static java.net.URI resolveDesignResource(java.lang.Object instance,
                                                 java.net.URI uri)
A convenience method for a client to invoke the method resolveDesignResource(URI) on the specified ResourceIdentifiers instance. This supports the use case where the class of the specified instance is not accessible by this class loader(s).

Parameters:
instance - an instance of ResourceIdentifiers
uri - the URI to be resolved against the design resource base URI
Returns:
the resulting URI
Since:
3.3.3 (DTP 1.9.2)
See Also:
resolveDesignResource(URI)

getDesignResourceBaseURI

public static java.net.URI getDesignResourceBaseURI(java.lang.Object instance)
A convenience method for a client to invoke the method getDesignResourceBaseURI() on the specified ResourceIdentifiers instance. This supports the use case where the class of the specified instance is not accessible by this class loader(s).

Parameters:
instance - an instance of ResourceIdentifiers
Returns:
the resulting URI
Since:
3.3.3 (DTP 1.9.2)
See Also:
#getDesignResourceBaseURI()}

resolveDesignResource

public java.net.URI resolveDesignResource(java.net.URI uri)
Resolves the specified URI against the base URI of an ODA consumer application's design resources. It uses the design resource URI Locator registered by an ODA consumer application to resolve a design resource URI.

Parameters:
uri - the URI to be resolved against the design resource base URI
Returns:
the resulting URI
Since:
DTP 1.7

getDesignResourceBaseURI

public java.net.URI getDesignResourceBaseURI()
Returns the base URI of the design resources of an ODA consumer application. The definition of a design resource is dependent on individual consumer application. The returned URI is application-dependent, and may be not well defined. In such case, the client should use resolveDesignResource(URI) or get the URI locator in getDesignResourceURILocator() to resolve a relative URI reference.

Returns:
base URI reference; may be null
See Also:
resolveDesignResource(URI), getDesignResourceURILocator()

setDesignResourceBaseURI

public void setDesignResourceBaseURI(java.net.URI baseURI)
Specifies the base URI of the design resources of an ODA consumer application. The definition of a design resource is dependent on individual consumer application. It registers an ResourceIdentifiers.URILocator that can be used by a client to resolve a resource URI against the specified baseURI. Any previously registered design resource URILocator and its base URI is replaced.

Parameters:
baseURI - base URI; may be null
See Also:
registerDesignResourceURILocator(URILocator)

getDesignResourceURILocator

public ResourceIdentifiers.URILocator getDesignResourceURILocator()
Returns the URI Locator registered by an ODA consumer application for its design resources. A custom ODA designer may use the URI locator to resolve a design resource URI.

Returns:
design resource URI locator; may be null if none is available
See Also:
getDesignResourceBaseURI()

registerDesignResourceURILocator

public void registerDesignResourceURILocator(ResourceIdentifiers.URILocator uriLocator)
Registers a URILocator defined by an ODA consumer application for its design resources. Replaces any previously registered design resources URILocator and its base URI.

Parameters:
uriLocator - a design resource URI locator
See Also:
setDesignResourceBaseURI(URI)

resolveResourceLocation

public java.net.URI resolveResourceLocation(java.lang.String resourcePath)
EXPERIMENTAL Converts and resolves the specified resource location path to a URI, based on the registered resource URILocator and its base URI. This will first attempt to use the application resources URILocator, if exists; otherwise, its design resources URILocator is used.

Parameters:
resourcePath - the path to be encoded and resolved to a URI; may be an absolute or relative path
Returns:
resolved URI; may be null if not able to resolve
Since:
3.3.2 (DTP 1.9)

encodeToURI

public static java.net.URI encodeToURI(java.lang.String filePath)
Encode non-US-ASCII characters in specified file path into an URI.

Parameters:
filePath - the string representation of a file,
Returns:
the encoded URI, or null if unable to encode
Since:
3.3.3 (DTP 1.9.2)