|
OSGi™ Service Platform Release 4 Version 4.2 |
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.osgi.service.application.ApplicationDescriptor
public abstract class ApplicationDescriptor
An OSGi service that represents an installed application and stores information about it. The application descriptor can be used for instance creation.
Field Summary | |
---|---|
static java.lang.String |
APPLICATION_CONTAINER
The property key for the application container of the application. |
static java.lang.String |
APPLICATION_COPYRIGHT
The property key for the localized copyright notice of the application. |
static java.lang.String |
APPLICATION_DESCRIPTION
The property key for the localized description of the application. |
static java.lang.String |
APPLICATION_DOCUMENTATION
The property key for the localized documentation of the application. |
static java.lang.String |
APPLICATION_ICON
The property key for the localized icon of the application. |
static java.lang.String |
APPLICATION_LAUNCHABLE
The property key for the launchable property of the application. |
static java.lang.String |
APPLICATION_LICENSE
The property key for the localized license of the application. |
static java.lang.String |
APPLICATION_LOCATION
The property key for the location of the application. |
static java.lang.String |
APPLICATION_LOCKED
The property key for the locked property of the application. |
static java.lang.String |
APPLICATION_NAME
The property key for the localized name of the application. |
static java.lang.String |
APPLICATION_PID
The property key for the unique identifier (PID) of the application. |
static java.lang.String |
APPLICATION_VENDOR
The property key for the name of the application vendor. |
static java.lang.String |
APPLICATION_VERSION
The property key for the version of the application. |
static java.lang.String |
APPLICATION_VISIBLE
The property key for the visibility property of the application. |
Constructor Summary | |
---|---|
protected |
ApplicationDescriptor(java.lang.String applicationId)
Constructs the ApplicationDescriptor . |
Method Summary | |
---|---|
java.lang.String |
getApplicationId()
Returns the identifier of the represented application. |
java.util.Map |
getProperties(java.lang.String locale)
Returns the properties of the application descriptor as key-value pairs. |
protected abstract java.util.Map |
getPropertiesSpecific(java.lang.String locale)
Container implementations can provide application model specific and/or container implementation specific properties via this method. |
protected abstract boolean |
isLaunchableSpecific()
This method is called by launch() to verify that according to the container, the application is launchable. |
ApplicationHandle |
launch(java.util.Map arguments)
Launches a new instance of an application. |
protected abstract ApplicationHandle |
launchSpecific(java.util.Map arguments)
Called by launch() to create and start a new instance in an application model specific way. |
void |
lock()
Sets the lock state of the application. |
protected abstract void |
lockSpecific()
This method is used to notify the container implementation that the corresponding application has been locked and it should update the application.locked service property accordingly. |
abstract boolean |
matchDNChain(java.lang.String pattern)
This method verifies whether the specified pattern
matches the Distinguished Names of any of the certificate chains
used to authenticate this application. |
ScheduledApplication |
schedule(java.lang.String scheduleId,
java.util.Map arguments,
java.lang.String topic,
java.lang.String eventFilter,
boolean recurring)
Schedules the application at a specified event. |
void |
unlock()
Unsets the lock state of the application. |
protected abstract void |
unlockSpecific()
This method is used to notify the container implementation that the corresponding application has been unlocked and it should update the application.locked service property accordingly. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String APPLICATION_NAME
public static final java.lang.String APPLICATION_ICON
public static final java.lang.String APPLICATION_PID
public static final java.lang.String APPLICATION_VERSION
public static final java.lang.String APPLICATION_VENDOR
public static final java.lang.String APPLICATION_VISIBLE
public static final java.lang.String APPLICATION_LAUNCHABLE
public static final java.lang.String APPLICATION_LOCKED
public static final java.lang.String APPLICATION_DESCRIPTION
public static final java.lang.String APPLICATION_DOCUMENTATION
public static final java.lang.String APPLICATION_COPYRIGHT
public static final java.lang.String APPLICATION_LICENSE
public static final java.lang.String APPLICATION_CONTAINER
public static final java.lang.String APPLICATION_LOCATION
Constructor Detail |
---|
protected ApplicationDescriptor(java.lang.String applicationId)
ApplicationDescriptor
.
applicationId
- The identifier of the application. Its value is also available
as the service.pid
service property of this
ApplicationDescriptor
service. This parameter must not
be null
.
java.lang.NullPointerException
- if the specified applicationId
is null.Method Detail |
---|
public final java.lang.String getApplicationId()
public abstract boolean matchDNChain(java.lang.String pattern)
pattern
matches the Distinguished Names of any of the certificate chains
used to authenticate this application.
The pattern
must adhere to the
syntax defined in ApplicationAdminPermission
for signer attributes.
This method is used by ApplicationAdminPermission.implies(java.security.Permission)
method
to match target ApplicationDescriptor
and filter.
pattern
- a pattern for a chain of Distinguished Names. It must not be null.
true
if the specified pattern matches at least
one of the certificate chains used to authenticate this application
java.lang.NullPointerException
- if the specified pattern
is null.
java.lang.IllegalStateException
- if the application descriptor was
unregisteredpublic final java.util.Map getProperties(java.lang.String locale)
Map
will include the service
properties of this ApplicationDescriptor
as well.
This method will call the getPropertiesSpecific
method
to enable the container implementation to insert application model and/or
container implementation specific properties.
The returned Map
will contain the standard OSGi service
properties as well
(e.g. service.id, service.vendor etc.) and specialized application
descriptors may offer further service properties. The returned Map contains
a snapshot of the properties. It will not reflect further changes in the
property values nor will the update of the Map change the corresponding
service property.
locale
- the locale string, it may be null, the value null means the
default locale. If the provided locale is the empty String
(""
)then raw (non-localized) values are returned.
java.lang.IllegalStateException
- if the application descriptor is unregisteredprotected abstract java.util.Map getPropertiesSpecific(java.lang.String locale)
locale
argument is not the empty String. The value
null
indicates to use the default locale, for other
values the specified locale should be used.
The returned Map
must contain the standard OSGi service
properties as well
(e.g. service.id, service.vendor etc.) and specialized application
descriptors may offer further service properties.
The returned Map
contains a snapshot of the properties. It will not reflect further changes in the
property values nor will the update of the Map change the corresponding
service property.
locale
- the locale to be used for localizing the properties.
If null
the default locale should be used. If it is
the empty String (""
) then raw (non-localized) values
should be returned.
java.lang.IllegalStateException
- if the application descriptor is unregisteredpublic final ApplicationHandle launch(java.util.Map arguments) throws ApplicationException
args
parameter specifies
the startup parameters for the instance to be launched, it may be null.
The following steps are made:
ApplicationException
with the reason code
ApplicationException.APPLICATION_LOCKED
.
launchSpecific()
method to create and start an application
instance.
ApplicationHandle
returned by the
launchSpecific()
The Map
argument of the launch method contains startup
arguments for the
application. The keys used in the Map must be non-null, non-empty String
objects. They can be standard or application
specific. OSGi defines the
org.osgi.triggeringevent
key to be used to
pass the triggering event to a scheduled application, however
in the future it is possible that other well-known keys will be defined.
To avoid unwanted clashes of keys, the following rules should be applied:
- The keys starting with the dash (-) character are application
specific, no well-known meaning should be associated with them.
- Well-known keys should follow the reverse domain name based naming.
In particular, the keys standardized in OSGi should start with
org.osgi.
.
The method is synchronous, it return only when the application instance was
successfully started or the attempt to start it failed.
This method never returns null
. If launching an application fails,
the appropriate exception is thrown.
- Parameters:
arguments
- Arguments for the newly launched application, may be null
- Returns:
- the registered ApplicationHandle, which represents the newly
launched application instance. Never returns
null
.
- Throws:
java.lang.SecurityException
- if the caller doesn't have "lifecycle"
ApplicationAdminPermission for the application.
ApplicationException
- if starting the application failed
java.lang.IllegalStateException
- if the application descriptor is unregistered
java.lang.IllegalArgumentException
- if the specified Map
contains invalid keys
(null objects, empty String
or a key that is not
String
)
launchSpecific
protected abstract ApplicationHandle launchSpecific(java.util.Map arguments)
throws java.lang.Exception
- Called by launch() to create and start a new instance in an application
model specific way. It also creates and registeres the application handle
to represent the newly created and started instance and registeres it.
The method is synchronous, it return only when the application instance was
successfully started or the attempt to start it failed.
This method must not return null
. If launching the application
failed, and exception must be thrown.
- Parameters:
arguments
- the startup parameters of the new application instance, may be
null
- Returns:
- the registered application model
specific application handle for the newly created and started
instance.
- Throws:
java.lang.IllegalStateException
- if the application descriptor is unregistered
java.lang.Exception
- if any problem occurs.
isLaunchableSpecific
protected abstract boolean isLaunchableSpecific()
- This method is called by launch() to verify that according to the
container, the application is launchable.
- Returns:
- true, if the application is launchable according to the
container, false otherwise.
- Throws:
java.lang.IllegalStateException
- if the application descriptor is unregistered
schedule
public final ScheduledApplication schedule(java.lang.String scheduleId,
java.util.Map arguments,
java.lang.String topic,
java.lang.String eventFilter,
boolean recurring)
throws InvalidSyntaxException,
ApplicationException
- Schedules the application at a specified event. Schedule information
should not get lost even if the framework or the device restarts so it
should be stored in a persistent storage. The method registers a
ScheduledApplication
service in Service Registry, representing
the created schedule.
The Map
argument of the method contains startup
arguments for the application. The keys used in the Map must be non-null,
non-empty String objects. The argument values must be
of primitive types, wrapper classes of primitive types, String
or arrays or collections of these.
The created schedules have a unique identifier within the scope of this
ApplicationDescriptor
. This identifier can be specified
in the scheduleId
argument. If this argument is null
,
the identifier is automatically generated.
- Parameters:
scheduleId
- the identifier of the created schedule. It can be null
,
in this case the identifier is automatically generated.arguments
- the startup arguments for the scheduled application, may be
nulltopic
- specifies the topic of the triggering event, it may contain a
trailing asterisk as wildcard, the empty string is treated as
"*", must not be nulleventFilter
- specifies and LDAP filter to filter on the properties of the
triggering event, may be nullrecurring
- if the recurring parameter is false then the application will
be launched only once, when the event firstly occurs. If the
parameter is true then scheduling will take place for every
event occurrence; i.e. it is a recurring schedule
- Returns:
- the registered scheduled application service
- Throws:
java.lang.NullPointerException
- if the topic is null
InvalidSyntaxException
- if the specified eventFilter
is not syntactically correct
ApplicationException
- if the schedule couldn't be created. The possible error
codes are
-
ApplicationException.APPLICATION_DUPLICATE_SCHEDULE_ID
if the specified scheduleId
is already used
for this ApplicationDescriptor
-
ApplicationException.APPLICATION_SCHEDULING_FAILED
if the scheduling failed due to some internal reason
(e.g. persistent storage error).
-
ApplicationException.APPLICATION_INVALID_STARTUP_ARGUMENT
if the specified startup argument doesn't satisfy the
type or value constraints of startup arguments.
java.lang.SecurityException
- if the caller doesn't have "schedule"
ApplicationAdminPermission for the application.
java.lang.IllegalStateException
- if the application descriptor is unregistered
java.lang.IllegalArgumentException
- if the specified Map
contains invalid keys
(null objects, empty String
or a key that is not
String
)
lock
public final void lock()
- Sets the lock state of the application. If an application is locked then
launching a new instance is not possible. It does not affect the already
launched instances.
- Throws:
java.lang.SecurityException
- if the caller doesn't have "lock" ApplicationAdminPermission
for the application.
java.lang.IllegalStateException
- if the application descriptor is unregistered
lockSpecific
protected abstract void lockSpecific()
- This method is used to notify the container implementation that the
corresponding application has been locked and it should update the
application.locked
service property accordingly.
- Throws:
java.lang.IllegalStateException
- if the application descriptor is unregistered
unlock
public final void unlock()
- Unsets the lock state of the application.
- Throws:
java.lang.SecurityException
- if the caller doesn't have "lock" ApplicationAdminPermission
for the application.
java.lang.IllegalStateException
- if the application descriptor is unregistered
unlockSpecific
protected abstract void unlockSpecific()
- This method is used to notify the container implementation that the
corresponding application has been unlocked and it should update the
application.locked
service property accordingly.
- Throws:
java.lang.IllegalStateException
- if the application descriptor is unregistered
Overview
Package
Class
Tree
Deprecated
Index
Help
OSGi™ Service Platform
Release 4 Version 4.2
PREV CLASS
NEXT CLASS
FRAMES
NO FRAMES
All Classes
SUMMARY: NESTED | FIELD | CONSTR | METHOD
DETAIL: FIELD | CONSTR | METHOD
Copyright © OSGi Alliance (2000, 2010). All Rights Reserved. Licensed under the OSGi Specification License, Version 1.0