* The {@code pattern} must adhere to the * syntax defined in {@link org.osgi.service.application.ApplicationAdminPermission} * for signer attributes. *
* This method is used by {@link ApplicationAdminPermission#implies(java.security.Permission)} method * to match target {@code ApplicationDescriptor} and filter. * * @param pattern a pattern for a chain of Distinguished Names. It must not be null. * @return {@code true} if the specified pattern matches at least * one of the certificate chains used to authenticate this application * @throws NullPointerException if the specified {@code pattern} is null. * @throws IllegalStateException if the application descriptor was * unregistered */ public abstract boolean matchDNChain(String pattern); /** * Returns the properties of the application descriptor as key-value pairs. * The return value contains the locale aware and unaware properties as * well. The returned {@code Map} will include the service * properties of this {@code ApplicationDescriptor} as well. *
* This method will call the {@code getPropertiesSpecific} method * to enable the container implementation to insert application model and/or * container implementation specific properties. *
* The returned {@link java.util.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. * * @param locale * the locale string, it may be null, the value null means the * default locale. If the provided locale is the empty String * ({@code ""})then raw (non-localized) values are returned. * * @return copy of the service properties of this application descriptor service, * according to the specified locale. If locale is null then the * default locale's properties will be returned. (Since service * properties are always exist it cannot return null.) * * @throws IllegalStateException * if the application descriptor is unregistered */ @SuppressWarnings({ "rawtypes", "unchecked" }) public final Map getProperties(String locale) { Map props = getPropertiesSpecific(locale); Boolean containerLocked = (Boolean) props.remove(APPLICATION_LOCKED); synchronized (locked) { if (containerLocked != null && containerLocked.booleanValue() != locked[0]) { if (locked[0]) lockSpecific(); else unlockSpecific(); } } /* replace the container's lock with the application model's lock, that's the correct */ props.put(APPLICATION_LOCKED, Boolean.valueOf(locked[0])); return props; } /** * Container implementations can provide application model specific * and/or container implementation specific properties via this * method. * * Localizable properties must be returned localized if the provided * {@code locale} argument is not the empty String. The value * {@code null} indicates to use the default locale, for other * values the specified locale should be used. * * The returned {@link java.util.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 {@code 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. * @param locale the locale to be used for localizing the properties. * If {@code null} the default locale should be used. If it is * the empty String ({@code ""}) then raw (non-localized) values * should be returned. * * @return the application model specific and/or container implementation * specific properties of this application descriptor. * * @throws IllegalStateException * if the application descriptor is unregistered */ @SuppressWarnings("rawtypes") protected abstract Map getPropertiesSpecific(String locale); /** * Launches a new instance of an application. The {@code args} parameter * specifies the startup parameters for the instance to be launched, it may * be null. *
* The following steps are made: *
* The {@code Map} argument of the launch method contains startup arguments * for the application. The keys used in the Map must be non-null, non-empty * {@code String} objects. They can be standard or application specific. * OSGi defines the {@code 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 method is synchronous, it return only when the application instance * was successfully started or the attempt to start it failed. *
* This method never returns {@code null}. If launching an application * fails, the appropriate exception is thrown. * * @param arguments Arguments for the newly launched application, may be * null * * @return the registered ApplicationHandle, which represents the newly * launched application instance. Never returns {@code null}. * * @throws SecurityException if the caller doesn't have "lifecycle" * ApplicationAdminPermission for the application. * @throws ApplicationException if starting the application failed * @throws IllegalStateException if the application descriptor is * unregistered * @throws IllegalArgumentException if the specified {@code Map} contains * invalid keys (null objects, empty {@code String} or a key that is * not {@code String}) */ @SuppressWarnings("rawtypes") public final ApplicationHandle launch(Map arguments) throws ApplicationException { SecurityManager sm = System.getSecurityManager(); if (sm != null) sm.checkPermission(new ApplicationAdminPermission(this, ApplicationAdminPermission.LIFECYCLE_ACTION)); synchronized (locked) { if (locked[0]) throw new ApplicationException(ApplicationException.APPLICATION_LOCKED, "Application is locked, can't launch!"); } if (!isLaunchableSpecific()) throw new ApplicationException(ApplicationException.APPLICATION_NOT_LAUNCHABLE, "Cannot launch the application!"); ArgumentsHelper.checkArgs(arguments, false); try { return launchSpecific(arguments); } catch (IllegalStateException ise) { throw ise; } catch (SecurityException se) { throw se; } catch (ApplicationException ae) { throw ae; } catch (Exception t) { throw new ApplicationException(ApplicationException.APPLICATION_INTERNAL_ERROR, t); } } /** * Called by launch() to create and start a new instance in an application * model specific way. It also creates and registers the application handle * to represent the newly created and started instance and registers 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 {@code null}. If launching the application * failed, and exception must be thrown. * * @param arguments * the startup parameters of the new application instance, may be * null * * @return the registered application model * specific application handle for the newly created and started * instance. * * @throws IllegalStateException * if the application descriptor is unregistered * @throws Exception * if any problem occurs. */ @SuppressWarnings("rawtypes") protected abstract ApplicationHandle launchSpecific(Map arguments) throws Exception; /** * This method is called by launch() to verify that according to the * container, the application is launchable. * * @return true, if the application is launchable according to the * container, false otherwise. * * @throws IllegalStateException * if the application descriptor is unregistered */ protected abstract boolean isLaunchableSpecific(); /** * 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 * {@link ScheduledApplication} service in Service Registry, representing * the created schedule. *
* The {@code Map} argument of the method contains startup arguments for the * application. The keys used in the Map must be non-null, non-empty * {@code String} objects. The argument values must be of primitive types, * wrapper classes of primitive types, {@code String} or arrays or * collections of these. *
* The created schedules have a unique identifier within the scope of this * {@code ApplicationDescriptor}. This identifier can be specified in the * {@code scheduleId} argument. If this argument is {@code null}, the * identifier is automatically generated. * * @param scheduleId the identifier of the created schedule. It can be * {@code null}, in this case the identifier is automatically * generated. * @param arguments the startup arguments for the scheduled application, may * be null * @param topic specifies the topic of the triggering event, it may contain * a trailing asterisk as wildcard, the empty string is treated as * "*", must not be null * @param eventFilter specifies and LDAP filter to filter on the properties * of the triggering event, may be null * @param recurring 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 * * @return the registered scheduled application service * * @throws NullPointerException if the topic is {@code null} * @throws InvalidSyntaxException if the specified {@code eventFilter} is * not syntactically correct * @throws ApplicationException if the schedule couldn't be created. The * possible error codes are *