Registrypublic class Registry extends Object | The Registry provides method to invoke,
register,
unregister, and query information about content handlers.
An application registers, for each content handler,
zero or more content types, suffixes, and actions.
Access to the registry is via the {@link #getRegistry getRegistry}
method. The Registry class is thread safe.
Applications are responsible for the thread safety of
Invocation objects passed as arguments to Registry methods.
Multiple content handlers can be registered for each type, suffix,
and action.
The types, suffixes, and actions registered for a handler
can be used to select a handler.
The content handler ID is set during registration and is
used to uniquely identify the content handler
and to enforce access controls.
A content handler is any application that is registered to
handle some content. It responds to requests and displays
or acts on the content.
Registration can occur dynamically or statically.
Static registration occurs during the installation of the
application package, while dynamic registration occurs via this API.
A content handler may be a Java or a non-Java application.
For example, MIDlet suites and Personal Basis Profile applications
using the Xlet application model can be content handlers.
Refer to the {@link ContentHandler ContentHandler}
class for information on registering Java platform content handlers.
When a content handler is processing an invocation, it may be
necessary to invoke another content handler before it is able
to satisfy the first request.
The invocation and chaining of content handlers is managed
to maintain the context and sequence across
application executions.
The term application is used more generally than the term
content handler.
The term application is used to refer to the
common handling for making requests, handling responses,
and querying the content handler registrations.
The term content handler is used for an application
that registers for types, suffixes, actions, etc. and processes
the requests queued to it.
Content Types
A content handler can register a set of types that it can handle.
Content types are simple opaque strings that are NOT case sensitive.
Type strings are not case sensitive, types that differ
only by case are treated as a single type.
Suffix Processing
A content handler can register a set of suffixes that identify
from the syntax of a URL the content it can handle.
Suffixes are NOT case sensitive.
Content Handler Actions
Each content handler may register a set of actions
it supports.
The set of actions is extensible but applications should
choose from the actions defined in the {@link ContentHandler}
class when they are appropriate.
The predefined actions are:
{@link ContentHandler#ACTION_OPEN open},
{@link ContentHandler#ACTION_EDIT edit},
{@link ContentHandler#ACTION_NEW new},
{@link ContentHandler#ACTION_SEND send},
{@link ContentHandler#ACTION_SAVE save},
{@link ContentHandler#ACTION_EXECUTE execute},
{@link ContentHandler#ACTION_SELECT select},
{@link ContentHandler#ACTION_INSTALL install},
{@link ContentHandler#ACTION_PRINT print}, and
{@link ContentHandler#ACTION_STOP stop}.
Content Handler IDs
The content handler ID is a string chosen by the
application vendor to identify the content handler. The
ID registered by a content handler MUST be unique and MUST NOT
match the prefix of any other registered content handler.
IDs are case sensitive and are treated as opaque strings.
They are compared for equality or as prefixes of IDs
when used to locate an appropriate content handler.
Content handler IDs should follow the form of
fully qualified Java class names or any naming
syntax that provides a natural way to disambiguate between
vendors. For example, IDs may be URLs
including scheme, authority (server), and path information.
For example, if registered in the order below,
the following content handler IDs would be valid
or invalid as indicated because there is an ambiguity due
to prefix comparisons.
com.sun.applications.calc - validcom.sun.applications.trig - validcom.sun.application - invalid,
this is the prefix of the calc IDcom.sun.applications.calc.decimal -
invalid, the calc ID is prefix of decimal
Java Application Class
The content handler to be launched is identified by the
application class. The class MUST contain entry point(s)
and be packaged according to the Java runtime environment.
For MIDP, the application class MUST extend
javax.microedition.midlet.MIDlet.
The application class uniquely identifies a content handler
within the application package, which is usually a JAR file.
Each application class can only be registered to a single content
handler. Registering a content handler for a class will replace any
content handler previously registered to that class.
Content Handler Authentication
Applications and content handlers using the API may,
for security purposes, need or want to authenticate
the invoked content handler or the invoking application.
The CHAPI implementation cooperates with the application management
software to authenticate the applications (if possible) and pass the
authentication information to the application. If the application
can be authenticated, then the
{@link ContentHandler#getAuthority ContentHandler.getAuthority}
method will return the authority used in the authentication.
While processing an invocation request the content handler can use the
{@link Invocation#getInvokingAuthority Invocation.getInvokingAuthority}
method to verify the authenticity of the invoking application.
Content Handler Access Control
The visibility and accessibility of a content handler
can be controlled by the content handler itself either through
dynamic or static registration. To restrict
access and visibility, the content handler MUST provide the IDs of
the content handlers that MUST be allowed access.
If any of the allowed IDs match
the beginning of the ID of the content handler requesting access, then the
application will be granted visibility and access to
the content handler. The comparison is performed as
if the java.lang.string.startsWith method was used.
The access controls are only visible to the content handler
itself using the method
{@link ContentHandlerServer#getAccessAllowed
ContentHandlerServer.getAccessAllowed}.
By default,
access is allowed to all applications and content handlers.
Access restrictions are established when the content handler is
registered with the {@link #register register} method.
Dynamic Registration
Dynamic registration is performed by
initializing the classname, types, suffixes,
actions, action names, ID, and access restrictions, and passing
them to the {@link #register register} method.
The {@link #unregister unregister} method removes
a registered content handler.
The current registrations can be examined by using various methods to
get the {@link #getTypes types},
{@link #getIDs IDs},
{@link #getSuffixes suffixes},
{@link #getActions actions},
or to find a content handler
by content handler {@link #getServer classname}, or
to get all of the matching content handlers
by {@link #forID ID},
by {@link #forType content type},
by {@link #forSuffix suffix}, or
by {@link #forAction action}.
Only content handlers that are accessible and visible to the
application will be returned.
Invoking a Content Handler
To invoke a content handler, an application initializes an
Invocation instance with the information needed to identify the
content and/or the content handler. Typically this could include the
URL, type, action, and content handler ID.
The application may also supply arguments and data, and set
whether a response is required.
The application may request information about the content
and the content handler that will process it before invocation.
Calling the {@link Registry#invoke Registry.invoke} method
starts the request.
When invoked, the ID, type, URL, and action are used to identify a
target content handler. If multiple content handlers are registered
for the ID, type, suffixes or action, the implementation can decide
which to use to satisfy the request. If the application needs to
select which handler to use, the
{@link Registry#findHandler findHandler} method will
return the set of matching ContentHandlers. The application can
choose from the content handlers returned and use
{@link Invocation#setID Invocation.setID}
to select a specific handler.
In a runtime environment in which only a single application can
run at a time, the invoking application must exit before the
content handler can be started to handle the request.
Invocation requests are queued so that the invoking
application and the content handler can be run sequentially in
resource-constrained environments.
The return value of {@link Registry#invoke invoke}
is true to indicate that the application must exit.
This allows the invoking application to save the users context
and leave the user interface, if any, with some visual that the
user will see until the content handler is ready.
Invocation processing involves the invoking application,
the invoked
content handler, and the application management software (AMS).
The implementation of the API and the AMS MUST implement the
queuing of invocations to the appropriate content handler and
the necessary interactions with the lifecycle to start and
restart applications and content handlers.
The {@link Registry#invoke invoke} methods initiate the request.
The URL, type, action, and ID, as described above, are used to
dispatch the request to an appropriate content handler.
If the content handler is not running, it MUST be started to process
the request. If the content handler is already running,
then the new request MUST be queued to the content handler.
Only a single instance of each content handler application can be
active at a time.
The {@link ContentHandlerServer} class is used to dequeue and process
requests. |
| Fields Summary |
|---|
| private static com.sun.midp.security.SecurityToken | classSecurityTokenThis class has a different security domain than the MIDlet suite | | private static final Object | mutexThe mutex used to avoid corruption between threads. | | private com.sun.midp.content.RegistryImpl | implThe reference to the RegistryImpl with the real implementation. |
| Constructors Summary |
|---|
private Registry(com.sun.midp.content.RegistryImpl impl)Constructor to create a new Registry with a RegistryImpl
and to insert it int the list of known Registry instances.
this.impl = impl;
|
| Methods Summary |
|---|
| public void | cancelGetResponse()Cancels a pending getResponse.
This method will force a thread blocked in a call to the
getResponse method for this Registry instance
to return early.
If no thread is blocked; this call has no effect.
impl.cancelGetResponse();
| | public ContentHandler[] | findHandler(Invocation invocation)Gets the registered content handlers that could be used for
this Invocation. Only handlers accessible to the application
are considered. The values for ID, type, URL, and
action are used in the following order:
- If the ID is non-null, then a candidate
handler is determined by the {@link #forID forID}
method with the parameter exact set to false.
The type and URL are ignored. If there is no handler that matches
the requested ID then a ContentHandlerException
is thrown.
- If the ID and type are
null and
the URL is non-null and
if the protocol supports typing of content, then
the type is determined
as described in {@link Invocation#findType}.
If the type cannot be determined from the content,
the type is set to null.
- If the ID is null and type is non-null,
then the set of candidate handlers is determined from the
{@link #forType forType} method.
If there are no handlers that match the requested type
then a ContentHandlerException is thrown.
- If both the ID and type are
null and
the URL is non-null and
if the protocol does not support typing of content
or the type was not available from the content,
then the set of candidate handlers
includes any handler with a suffix that matches the
end of the path component of the URL.
If there are no handlers that match a registered
suffix then a ContentHandlerException is thrown.
- If the ID, type, and URL are all null, the set of candidate
handlers includes all of the accessible handlers.
- If the action is non-null, the set of candidate handlers
is reduced to contain only handlers that support the
action.
- If the set of candidate handlers is empty
then a ContentHandlerException is thrown.
The calling thread blocks while the ID and type are being determined.
If a network access is needed there may be an associated delay.
return impl.findHandler(invocation.getInvocImpl());
| | private static com.sun.midp.content.RegistryImpl | findRegistryImpl(java.lang.String classname)Gets the RegistryImpl for the classname.
Create the Registry instance if it has not already been created.
synchronized (mutex) {
RegistryImpl impl =
RegistryImpl.getRegistryImpl(classname, classSecurityToken);
// Make sure there is a Registry;
if (impl.getRegistry() == null) {
impl.setRegistry(new Registry(impl));
}
return impl;
}
| | public ContentHandler[] | forAction(java.lang.String action)Gets the registered content handlers that support the action.
Only content handlers that are visible and accessible to this
application are returned.
return impl.forAction(action);
| | public ContentHandler | forID(java.lang.String ID, boolean exact)Gets the registered content handler for the ID.
The query can be for an exact match or for the handler
matching the prefix of the requested ID.
Only a content handler which is visible to and accessible to this
application will be returned.
The forID method may be useful for applications
with multiple components or subsystems
to define a base ID for the application.
A request to a particular component can be made by appending an
additional string to the base ID. The additional string can be
used by the handler itself to dispatch to
the component or subsystem. The forID method can be used to
query for the registered content handler.
return impl.forID(ID, exact);
| | public ContentHandler[] | forSuffix(java.lang.String suffix)Gets the content handlers for the suffix.
Only content handlers that are visible and accessible to this
application are returned.
return impl.forSuffix(suffix);
| | public ContentHandler[] | forType(java.lang.String type)Gets the registered content handlers for the content type.
Only content handlers that are visible and accessible to this
application are returned.
return impl.forType(type);
| | public java.lang.String[] | getActions()Gets the unique actions of the registered content handlers.
No duplicate strings will be returned.
After a successful registration the content handler's action(s),
if any, will appear in this list.
Only content handlers that this application is
allowed to access will be included.
return impl.getActions();
| | public java.lang.String | getID()Gets the content handler ID for the current application.
The ID uniquely identifies the content handler.
If the application is a content handler as returned from
{@link #getServer getServer} then the ID MUST be
the content handler ID returned from
{@link ContentHandlerServer#getID ContentHandlerServer.getID}.
Otherwise, the ID will be generated for the profile.
The package documentation
for "Content Handlers and the Mobile Information Device Profile"
defines the value for MIDP.
return impl.getID();
| | public java.lang.String[] | getIDs()Gets the IDs of the registered content handlers.
Only content handlers that this application is
allowed to access will be included.
return impl.getIDs();
| | public static javax.microedition.content.Registry | getRegistry(java.lang.String classname)Gets the Registry for the application or content handler
that will be calling registry methods.
The application is identified by the classname that implements
the lifecycle of the Java runtime environment.
The classname must be the name of a registered application class
or a registered content handler.
For a MIDP implementation,
application classes must be registered with the
MIDlet-<n> attribute; content handlers are
registered with the MicroEdition-Handler-<n>
attribute or the {@link #register register} method.
// Find the RegistryImpl instance and get/create the Registry
try {
return findRegistryImpl(classname).getRegistry();
} catch (ContentHandlerException che) {
throw new IllegalArgumentException(che.getMessage());
}
| | public Invocation | getResponse(boolean wait)Gets the next Invocation response pending for this application.
If requested, the method waits until an Invocation response
is available.
The method can be unblocked with a call to
{@link #cancelGetResponse cancelGetResponse}.
The application can process the Invocation based on
its status. The status is one of
OK, CANCELLED, ERROR,
or INITIATED.
If the Invocation was invoked with
{@link #invoke(Invocation invocation, Invocation previous)},
the getPrevious method MUST return the
previous Invocation.
If the status of the previous Invocation is HOLD
then its status is restored to ACTIVE.
If the original Invocation instance is reachable, then it
MUST be updated with the values from the response
and be returned to the application. If it is not
reachable, then a new instance is returned from
getResponse with the response values.
Invocation response = new Invocation();
response = impl.getResponse(wait, response.getInvocImpl());
return response;
| | public static ContentHandlerServer | getServer(java.lang.String classname)Gets the content handler server registered for the content
handler.
The classname MUST be registered as
a content handler in the current application package using
either the {@link #register register} method or
the static registration attributes.
RegistryImpl registryImpl = findRegistryImpl(classname);
// Insure only one thread promotes to ContentHandlerServer
ContentHandlerImpl server = null;
synchronized (mutex) {
server = registryImpl.getServer();
if (server == null) {
throw new ContentHandlerException("No registered handler",
ContentHandlerException.NO_REGISTERED_HANDLER);
}
if (!(server instanceof ContentHandlerServer)) {
// Not already a ContentHandlerServer; replace
server = new ContentHandlerServerImpl(server);
registryImpl.setServer(server);
}
}
return (ContentHandlerServer)server;
| | public java.lang.String[] | getSuffixes()Gets the unique suffixes of the registered content handlers.
Suffix strings are not case sensitive, suffixes that differ
only by case are treated as a single suffix.
Each suffix is returned only once.
After a successful registration the content handler's suffix(es),
if any, will appear in this list.
Only content handlers that this application is
allowed to access will be included.
return impl.getSuffixes();
| | public java.lang.String[] | getTypes()Gets all of the unique content types for which there are registered
handlers.
Type strings are not case sensitive, types that differ
only by case are treated as a single type.
Each type is returned only once.
After a successful registration, the content handler's type(s),
if any, will appear in this list.
Only content handlers that this application is
allowed to access will be included.
return impl.getTypes();
| | public boolean | invoke(Invocation invocation, Invocation previous)Checks the Invocation and uses the ID, type, URL, and action,
if present, to find a matching ContentHandler and queues this
request to it.
If the previous Invocation is null, then
a new transaction is created; otherwise, this
Invocation will use the same transaction as the
previous Invocation.
The status of this Invocation MUST be INIT.
If there is a previous Invocation, that Invocation MUST
have a status of ACTIVE and this Invocation MUST
require a response.
Candidate content handlers are found as described in
{@link #findHandler findHandler}. If any handlers are
found, one is selected for this Invocation.
The choice of content handler is implementation dependent.
A copy of the Invocation is made, the status is set to
ACTIVE and then queued to the
target content handler.
If the invoked content handler is not running, it MUST be started
as described in Invoking a Content Handler.
The status of this Invocation is set to WAITING.
If there is a non-null previous Invocation,
its status is set to HOLD.
The previous Invocation is saved in the waiting
Invocation.
It can be retrieved by the getPrevious method.
The calling thread blocks while the content handler is being determined.
If a network access is needed, there may be an associated delay.
if (invocation.getStatus() != Invocation.INIT) {
throw new IllegalStateException();
}
if (previous != null &&
previous.getStatus() != Invocation.ACTIVE) {
throw new IllegalStateException();
}
InvocationImpl invocImpl = invocation.getInvocImpl();
InvocationImpl prevImpl = null;
if (previous != null) {
prevImpl = previous.getInvocImpl();
}
return impl.invoke(invocImpl, prevImpl);
| | public boolean | invoke(Invocation invocation)Checks the Invocation and uses the ID, type, URL, and action,
if present, to find a matching ContentHandler and queues this
request to it.
The behavior is identical to
invoke(invocation, null).
return invoke(invocation, null);
| | public ContentHandlerServer | register(java.lang.String classname, java.lang.String[] types, java.lang.String[] suffixes, java.lang.String[] actions, ActionNameMap[] actionnames, java.lang.String ID, java.lang.String[] accessAllowed)Registers the application class using content
type(s), suffix(es), and action(s), action name(s),
access restrictions and content handler ID.
This method will replace any content handler
registration in the application package
that has the same classname.
The update occurs atomically: the update to the registry
either occurs or it does not.
The content handler may register the following items:
- zero or more content types
- zero or more suffixes
- zero or more actions
- zero or more mappings from actions to action names
- zero or more IDs of applications allowed access
- an optional application ID
If no exceptions are thrown, then the type(s), suffix(s), action(s),
action names, access restrictions, and ID
will be registered for the application class.
If an exception is thrown, then the previous registration, if
any, will not be removed or modified.
// First register the new/replacement handler
impl.register(classname, types, suffixes,
actions, actionnames, ID, accessAllowed);
// Return the value from {#link #getServer(classname)}.
return getServer(classname);
| | public boolean | reinvoke(Invocation invocation)Reinvokes the Invocation and uses the ID, type, URL, and action
to find a matching ContentHandler and re-queues this request to
it. Reinvocation is used to delegate the handling of an active
Invocation to another content handler.
The processing of the Invocation instance is complete and the
status is set to OK. Responses to the
reinvocation will be queued to the original invoking
application, if a response is required.
The status of this Invocation MUST be ACTIVE.
Candidate content handlers are found as described in
{@link #findHandler findHandler}. If any handlers are
found, one is selected for this Invocation.
The choice of content handler is implementation dependent.
The status of this Invocation is set to OK.
A copy of the Invocation is made, the status is set to
ACTIVE, and then queued to the
target content handler.
If the invoked content handler application is not running,
it MUST be started
as described in Invocation Processing.
The calling thread blocks while the content handler is being determined.
If a network access is needed there may be an associated delay.
if (invocation.getStatus() != Invocation.ACTIVE) {
throw new IllegalStateException();
}
return impl.reinvoke(invocation.getInvocImpl());
| | public void | setListener(ResponseListener listener)Sets the listener to be notified when a new response is
available for the application context. The request must
be retrieved using {@link #getResponse getResponse}.
If the listener is non-null and a response is
available, the listener MUST be notified.
Note that if getResponse is being called concurrently
with the listener then the listener may not be called because
the response has already been returned to the application.
The invocationResponseNotify is only used as a hint that
a response may be available.
impl.setListener(listener);
| | public boolean | unregister(java.lang.String classname)Removes the content handler registration for the application
class and any bindings made during registration to the content ID,
type(s), suffix(es), and action(s), etc.
Only content handlers registered either statically or dynamically
in the current application package will be removed.
return impl.unregister(classname);
|
|
