| java.lang.Object
 javax.microedition.content.Registry
| Registry | | public class Registry (Code) | | 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
Registry.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
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
ContentHandler
class when they are appropriate.
The predefined actions are:
ContentHandler.ACTION_OPEN open ,
ContentHandler.ACTION_EDIT edit ,
ContentHandler.ACTION_NEW new ,
ContentHandler.ACTION_SEND send ,
ContentHandler.ACTION_SAVE save ,
ContentHandler.ACTION_EXECUTE execute ,
ContentHandler.ACTION_SELECT select ,
ContentHandler.ACTION_INSTALL install ,
ContentHandler.ACTION_PRINT print , and
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
ContentHandler.getAuthority ContentHandler.getAuthority method will return the authority used in the authentication.
While processing an invocation request the content handler can use the
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
ContentHandlerServer.getAccessAllowedContentHandlerServer.getAccessAllowed .
By default,
access is allowed to all applications and content handlers.
Access restrictions are established when the content handler is
registered with the
Registry.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
Registry.register register method.
The
Registry.unregister unregister method removes
a registered content handler.
The current registrations can be examined by using various methods to
get the
Registry.getTypes types ,
Registry.getIDs IDs ,
Registry.getSuffixes suffixes ,
Registry.getActions actions ,
or to find a content handler
by content handler
Registry.getServer classname , or
to get all of the matching content handlers
by
Registry.forID ID ,
by
Registry.forType content type ,
by
Registry.forSuffix suffix , or
by
Registry.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
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
Registry.findHandler findHandler method will
return the set of matching ContentHandlers. The application can
choose from the content handlers returned and use
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
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
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
ContentHandlerServer class is used to dequeue and process
requests.
|
| Method Summary | |
| public void | cancelGetResponse()
Cancels a pending getResponse. | | public ContentHandler[] | findHandler(Invocation invocation)
Gets the registered content handlers that could be used for
this Invocation. | | public ContentHandler[] | forAction(String action)
Gets the registered content handlers that support the action. | | public ContentHandler | forID(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. | | public ContentHandler[] | forSuffix(String suffix)
Gets the content handlers for the suffix. | | public ContentHandler[] | forType(String type)
Gets the registered content handlers for the content type. | | public String[] | getActions()
Gets the unique actions of the registered content handlers. | | public String | getID()
Gets the content handler ID for the current application. | | public String[] | getIDs()
Gets the IDs of the registered content handlers. | | public static Registry | getRegistry(String classname)
Gets the Registry for the application or content handler
that will be calling registry methods. | | 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
Registry.cancelGetResponse cancelGetResponse .
The application can process the Invocation based on
its status. | | public static ContentHandlerServer | getServer(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
Registry.register register method or
the static registration attributes. | | public String[] | getSuffixes()
Gets the unique suffixes of the registered content handlers. | | public String[] | getTypes()
Gets all of the unique content types for which there are registered
handlers. | | 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
Registry.findHandler findHandler . | | 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. | | public ContentHandlerServer | register(String classname, String[] types, String[] suffixes, String[] actions, ActionNameMap[] actionnames, String ID, 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.
Parameters:
classname - the name of an application class orcontent handler in this application package;the value MUST NOT be null;and the handler MUST implement the lifecycle of the Java runtimeenvironment
Parameters:
types - an array of types to register;if null it is treated the same as an empty array
Parameters:
suffixes - an array of suffixes to register;if null it is treated the same as an empty array
Parameters:
actions - an array of actions to register;if null it is treated the same as an empty array
Parameters:
actionnames - an array of ActionNameMaps to register;if null it is treated the same as an empty array
Parameters:
ID - the content handler ID; if nulla default non-null value MUST be provided by the implementation
Parameters:
accessAllowed - the IDs of applications and contenthandlers that areallowed visibility and access to this content handler;if null or an empty array then all applications and content handlers are allowed access;otherwise ONLY applications and content handlers with matching IDsare allowed access. | | 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. | | public void | setListener(ResponseListener listener)
Sets the listener to be notified when a new response is
available for the application context. | | public boolean | unregister(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. |
| cancelGetResponse | | public void cancelGetResponse()(Code) | | 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.
|
| findHandler | | public ContentHandler[] findHandler(Invocation invocation) throws IOException, ContentHandlerException, SecurityException(Code) | | 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
Registry.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
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
Registry.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.
Parameters:
invocation - the ID, type, action, and URL thatare needed to identify one or more content handlers;must not be null an array of the ContentHandler(s)that could be used for this Invocation; MUST NOT be null;
exception:
IOException - is thrown if access to the content fails
exception:
ContentHandlerException - is thrown with a reason ofNO_REGISTERED_HANDLER ifthere is no registered content handler thatmatches the requested ID, type, URL, and action
exception:
IllegalArgumentException - is thrown if ID, type, URL,and action are all null orif the content is accessed via the URL and the URL is invalid
exception:
NullPointerException - is thrown if theinvocation is null
exception:
SecurityException - is thrown if access to the contentis not permitted |
| forAction | | public ContentHandler[] forAction(String action)(Code) | | Gets the registered content handlers that support the action.
Only content handlers that are visible and accessible to this
application are returned.
Parameters:
action - content handlers for which the action is supported an array of the ContentHandlers registeredfor the action; MUST NOT be null;an empty array is returned if no ContentHandlersare accessible to this application
exception:
NullPointerException - if action isnull |
| forID | | public ContentHandler forID(String ID, boolean exact)(Code) | | 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.
Parameters:
ID - the content handler application ID of the contenthandler requested
Parameters:
exact - true to require an exact match;false to allow a registered content handler IDto match a prefix of the requested ID the content handler that matches the ID,otherwise null
exception:
NullPointerException - if ID isnull |
| forSuffix | | public ContentHandler[] forSuffix(String suffix)(Code) | | Gets the content handlers for the suffix.
Only content handlers that are visible and accessible to this
application are returned.
Parameters:
suffix - the suffix to be used to get the associatedcontent handlers an array of the ContentHandlers registeredfor the suffix; MUST NOT be null.An empty array is returned if there are none accessible tothis application
exception:
NullPointerException - if suffix isnull |
| forType | | public ContentHandler[] forType(String type)(Code) | | Gets the registered content handlers for the content type.
Only content handlers that are visible and accessible to this
application are returned.
Parameters:
type - the type of the requested content handlers an array of the ContentHandlers registeredfor the type; MUST NOT be null.An empty array is returned if there are noContentHandlers accessible tothis application with the type equal to the request type.
exception:
NullPointerException - if type isnull |
| getActions | | public String[] getActions()(Code) | | 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.
an array of content handler actions;MUST NOT be null |
| getID | | public String getID()(Code) | | 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
Registry.getServer getServer then the ID MUST be
the content handler ID returned from
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.
the ID; MUST NOT be null |
| getIDs | | public String[] getIDs()(Code) | | Gets the IDs of the registered content handlers.
Only content handlers that this application is
allowed to access will be included.
an array of content handler IDs;MUST NOT be null |
| getRegistry | | public static Registry getRegistry(String classname)(Code) | | 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
Registry.register register method.
Parameters:
classname - the application class a Registry instance providing access to content handlerregistrations and invocations; MUST NOT be null
exception:
IllegalArgumentException - is thrown if the classnameis not a registered application or content handler
exception:
NullPointerException - if classname isnull |
| getResponse | | public Invocation getResponse(boolean wait)(Code) | | 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
Registry.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
Registry.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.
Parameters:
wait - true if the methodMUST wait for an Invocation if one is not available;otherwise false if the method MUST NOT wait the next pending response Invocation or nullif the wait is false and no Invocation is available orif cancelled with Registry.cancelGetResponse
See Also: Registry.invoke
See Also: Registry.cancelGetResponse |
| getServer | | public static ContentHandlerServer getServer(String classname) throws ContentHandlerException(Code) | | 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
Registry.register register method or
the static registration attributes.
Parameters:
classname - the name of an application class orcontent handler registered by this application package the content handler for the registeredclassname registered by this application package;MUST NOT be null
exception:
NullPointerException - if classname isnull
exception:
ContentHandlerException - is thrown with a reason ofNO_REGISTERED_HANDLER if there is nocontent handler registered for the classname in the currentapplication package |
| getSuffixes | | public String[] getSuffixes()(Code) | | 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.
an array of content handler suffixes;MUST NOT be null |
| getTypes | | public String[] getTypes()(Code) | | 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.
an array of types; MUST NOT be null |
| invoke | | public boolean invoke(Invocation invocation, Invocation previous) throws IllegalArgumentException, IOException, ContentHandlerException, SecurityException(Code) | | 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
Registry.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.
Parameters:
invocation - the Invocation containing the target ID, type, URL,actions, arguments, and responseRequired parameters;MUST NOT be null
Parameters:
previous - a previous Invocation for this Invocation;may be null true if the application MUSTvoluntarily exit to allow the target content handler to be started;false otherwise
exception:
IllegalArgumentException - is thrown if: - the ID, type, URL, and action are all
null, - the argument array contains any
nullreferences, or - the content is accessed via the URL and the URL isinvalid, or
- the
invocation.getResponseRequiredmethod returns false and previous is non-null
exception:
IOException - is thrown if access to the content fails
exception:
ContentHandlerException - is thrown with a reason ofNO_REGISTERED_HANDLER ifthere is no registered content handler thatmatches the requested ID, type, URL, and action
exception:
IllegalStateException - is thrown if the status of thisInvocation is not INIT or if the status of the previousInvocation, if any, is not ACTIVE
exception:
NullPointerException - is thrown if theinvocation is null
exception:
SecurityException - if access to the content is not permitted |
| invoke | | public boolean invoke(Invocation invocation) throws IllegalArgumentException, IOException, ContentHandlerException, SecurityException(Code) | | 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).
Parameters:
invocation - the Invocation containing the target ID, type,URL, action, arguments, and responseRequired parameters;MUST NOT be null true if the application MUSTvoluntarily exit to allow the target content handler to be started;false otherwise
exception:
IllegalArgumentException - is thrown if:- the ID, type, URL, and action are all
null, or - the content is accessed via the URL and the URL isinvalid, or
- the argument array contains any
nullreferences
exception:
IOException - is thrown if access to the content fails
exception:
ContentHandlerException - is thrown with a reason ofNO_REGISTERED_HANDLER ifthere is no registered content handler thatmatches the requested ID, type, URL, and action
exception:
IllegalStateException - is thrown if the status of thisInvocation is not INIT
exception:
NullPointerException - is thrown if theinvocation is null
exception:
SecurityException - if access to the content is not permitted |
| register | | public ContentHandlerServer register(String classname, String[] types, String[] suffixes, String[] actions, ActionNameMap[] actionnames, String ID, String[] accessAllowed) throws SecurityException, IllegalArgumentException, ClassNotFoundException, ContentHandlerException(Code) | | 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.
Parameters:
classname - the name of an application class orcontent handler in this application package;the value MUST NOT be null;and the handler MUST implement the lifecycle of the Java runtimeenvironment
Parameters:
types - an array of types to register;if null it is treated the same as an empty array
Parameters:
suffixes - an array of suffixes to register;if null it is treated the same as an empty array
Parameters:
actions - an array of actions to register;if null it is treated the same as an empty array
Parameters:
actionnames - an array of ActionNameMaps to register;if null it is treated the same as an empty array
Parameters:
ID - the content handler ID; if nulla default non-null value MUST be provided by the implementation
Parameters:
accessAllowed - the IDs of applications and contenthandlers that areallowed visibility and access to this content handler;if null or an empty array then all applications and content handlers are allowed access;otherwise ONLY applications and content handlers with matching IDsare allowed access. the registered ContentHandler; MUST NOT be null
exception:
NullPointerException - if any of the following items isnull: classname- any array element of
types, suffixes,actions, actionnames, andaccessAllowed
exception:
IllegalArgumentException - is thrown:- if any of the
types, suffix,actions, or accessAllowedstrings have a length of zero, or - if the
classname does not implement the validlifecycle for the Java runtime environment, - if the ID has a length of zero or contains anycontrol character or space (U+0000-U+00020),
- if the sequence of actions in any ActionNameMap is not the same as the sequence of
actions,or - if the locales of the ActionNameMaps are not unique.
exception:
ClassNotFoundException - if the classnameis not present
exception:
ContentHandlerException - with an error code of ContentHandlerException.AMBIGUOUS if ID(or if ID is null, the default ID)is a prefix of any registered handler or if any registeredhandler ID is a prefix of this ID,except where the registration is replacing or updating an existing registration with the same classname
exception:
SecurityException - if registrationis not permitted |
| reinvoke | | public boolean reinvoke(Invocation invocation) throws IllegalArgumentException, IOException, ContentHandlerException, SecurityException(Code) | | 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
Registry.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.
Parameters:
invocation - an Invocation containing the target ID, type,action, arguments, and responseRequired parameters;MUST NOT be null true if the application MUSTvoluntarily exit to allow the target content handler to be started;false otherwise
exception:
IllegalArgumentException - is thrown if: - the ID, type, and URL are all
null, or - the content is accessed via the URL and the URL isinvalid, or
- the argument array contains any
nullreferences
exception:
IOException - is thrown if access to the content fails
exception:
ContentHandlerException - is thrown with a reason of:NO_REGISTERED_HANDLER ifthere is no registered content handler thatmatches the requested ID, type, URL, and action
exception:
IllegalStateException - is thrown if the status of thisInvocation is not ACTIVE
exception:
NullPointerException - is thrown if theinvocation is null
exception:
SecurityException - if access to the content is not permitted |
| setListener | | public void setListener(ResponseListener listener)(Code) | | Sets the listener to be notified when a new response is
available for the application context. The request must
be retrieved using
Registry.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.
Parameters:
listener - the listener to register;null to remove the listener |
| unregister | | public boolean unregister(String classname)(Code) | | 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.
Parameters:
classname - the name of the content handler class true if the content handler registeredby this application was found and removed;false otherwise
exception:
NullPointerException - if classname isnull |
|
|