felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From christ...@apache.org
Subject svn commit: r662399 [7/9] - in /felix/trunk/deploymentadmin: ./ service/ service/src/ service/src/main/ service/src/main/java/ service/src/main/java/org/ service/src/main/java/org/apache/ service/src/main/java/org/apache/felix/ service/src/main/java/or...
Date Mon, 02 Jun 2008 11:40:01 GMT
Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/AttributeDefinition.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/AttributeDefinition.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/AttributeDefinition.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/AttributeDefinition.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,279 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/AttributeDefinition.java,v 1.13 2006/06/16 16:31:23 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.metatype;
+
+/**
+ * An interface to describe an attribute.
+ * 
+ * <p>
+ * An <code>AttributeDefinition</code> object defines a description of the data
+ * type of a property/attribute.
+ * 
+ * @version $Revision: 1.13 $
+ */
+public interface AttributeDefinition {
+	/**
+	 * The <code>STRING</code> (1) type.
+	 * 
+	 * <p>
+	 * Attributes of this type should be stored as <code>String</code>,
+	 * <code>Vector</code> with <code>String</code> or <code>String[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	STRING		= 1;
+	/**
+	 * The <code>LONG</code> (2) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Long</code>,
+	 * <code>Vector</code> with <code>Long</code> or <code>long[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	LONG		= 2;
+	/**
+	 * The <code>INTEGER</code> (3) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Integer</code>,
+	 * <code>Vector</code> with <code>Integer</code> or <code>int[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	INTEGER		= 3;
+	/**
+	 * The <code>SHORT</code> (4) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Short</code>,
+	 * <code>Vector</code> with <code>Short</code> or <code>short[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	SHORT		= 4;
+	/**
+	 * The <code>CHARACTER</code> (5) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Character</code>,
+	 * <code>Vector</code> with <code>Character</code> or <code>char[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	CHARACTER	= 5;
+	/**
+	 * The <code>BYTE</code> (6) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Byte</code>,
+	 * <code>Vector</code> with <code>Byte</code> or <code>byte[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	BYTE		= 6;
+	/**
+	 * The <code>DOUBLE</code> (7) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Double</code>,
+	 * <code>Vector</code> with <code>Double</code> or <code>double[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	DOUBLE		= 7;
+	/**
+	 * The <code>FLOAT</code> (8) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Float</code>,
+	 * <code>Vector</code> with <code>Float</code> or <code>float[]</code> objects,
+	 * depending on the <code>getCardinality()</code> value.
+	 */
+	public static final int	FLOAT		= 8;
+	/**
+	 * The <code>BIGINTEGER</code> (9) type.
+	 * 
+	 * Attributes of this type should be stored as <code>BigInteger</code>,
+	 * <code>Vector</code> with <code>BigInteger</code> or <code>BigInteger[]</code>
+	 * objects, depending on the <code>getCardinality()</code> value.
+	 * 
+	 * @deprecated As of 1.1.
+	 */
+	public static final int	BIGINTEGER	= 9;
+	/**
+	 * The <code>BIGDECIMAL</code> (10) type.
+	 * 
+	 * Attributes of this type should be stored as <code>BigDecimal</code>,
+	 * <code>Vector</code> with <code>BigDecimal</code> or <code>BigDecimal[]</code>
+	 * objects depending on <code>getCardinality()</code>.
+	 * 
+	 * @deprecated As of 1.1.
+	 */
+	public static final int	BIGDECIMAL	= 10;
+	/**
+	 * The <code>BOOLEAN</code> (11) type.
+	 * 
+	 * Attributes of this type should be stored as <code>Boolean</code>,
+	 * <code>Vector</code> with <code>Boolean</code> or <code>boolean[]</code> objects
+	 * depending on <code>getCardinality()</code>.
+	 */
+	public static final int	BOOLEAN		= 11;
+
+	/**
+	 * Get the name of the attribute. This name may be localized.
+	 * 
+	 * @return The localized name of the definition.
+	 */
+	public String getName();
+
+	/**
+	 * Unique identity for this attribute.
+	 * 
+	 * Attributes share a global namespace in the registry. E.g. an attribute
+	 * <code>cn</code> or <code>commonName</code> must always be a <code>String</code>
+	 * and the semantics are always a name of some object. They share this
+	 * aspect with LDAP/X.500 attributes. In these standards the OSI Object
+	 * Identifier (OID) is used to uniquely identify an attribute. If such an
+	 * OID exists, (which can be requested at several standard organisations and
+	 * many companies already have a node in the tree) it can be returned here.
+	 * Otherwise, a unique id should be returned which can be a Java class name
+	 * (reverse domain name) or generated with a GUID algorithm. Note that all
+	 * LDAP defined attributes already have an OID. It is strongly advised to
+	 * define the attributes from existing LDAP schemes which will give the OID.
+	 * Many such schemes exist ranging from postal addresses to DHCP parameters.
+	 * 
+	 * @return The id or oid
+	 */
+	public String getID();
+
+	/**
+	 * Return a description of this attribute.
+	 * 
+	 * The description may be localized and must describe the semantics of this
+	 * type and any constraints.
+	 * 
+	 * @return The localized description of the definition.
+	 */
+	public String getDescription();
+
+	/**
+	 * Return the cardinality of this attribute.
+	 * 
+	 * The OSGi environment handles multi valued attributes in arrays ([]) or in
+	 * <code>Vector</code> objects. The return value is defined as follows:
+	 * 
+	 * <pre>
+	 * 
+	 *    x = Integer.MIN_VALUE    no limit, but use Vector
+	 *    x &lt; 0                    -x = max occurrences, store in Vector
+	 *    x &gt; 0                     x = max occurrences, store in array []
+	 *    x = Integer.MAX_VALUE    no limit, but use array []
+	 *    x = 0                     1 occurrence required
+	 *  
+	 * </pre>
+	 * 
+	 * @return The cardinality of this attribute. 
+	 */
+	public int getCardinality();
+
+	/**
+	 * Return the type for this attribute.
+	 * 
+	 * <p>
+	 * Defined in the following constants which map to the appropriate Java
+	 * type. <code>STRING</code>,<code>LONG</code>,<code>INTEGER</code>,
+	 * <code>CHAR</code>,<code>BYTE</code>,<code>DOUBLE</code>,<code>FLOAT</code>,
+	 * <code>BOOLEAN</code>.
+	 *
+	 * @return The type for this attribute.
+	 */
+	public int getType();
+
+	/**
+	 * Return a list of option values that this attribute can take.
+	 * 
+	 * <p>
+	 * If the function returns <code>null</code>, there are no option values
+	 * available.
+	 * 
+	 * <p>
+	 * Each value must be acceptable to validate() (return "") and must be a
+	 * <code>String</code> object that can be converted to the data type defined
+	 * by getType() for this attribute.
+	 * 
+	 * <p>
+	 * This list must be in the same sequence as <code>getOptionLabels()</code>.
+	 * I.e. for each index i in <code>getOptionValues</code>, i in
+	 * <code>getOptionLabels()</code> should be the label.
+	 * 
+	 * <p>
+	 * For example, if an attribute can have the value male, female, unknown,
+	 * this list can return
+	 * <code>new String[] { "male", "female", "unknown" }</code>.
+	 * 
+	 * @return A list values
+	 */
+	public String[] getOptionValues();
+
+	/**
+	 * Return a list of labels of option values.
+	 * 
+	 * <p>
+	 * The purpose of this method is to allow menus with localized labels. It is
+	 * associated with <code>getOptionValues</code>. The labels returned here are
+	 * ordered in the same way as the values in that method.
+	 * 
+	 * <p>
+	 * If the function returns <code>null</code>, there are no option labels
+	 * available.
+	 * <p>
+	 * This list must be in the same sequence as the <code>getOptionValues()</code>
+	 * method. I.e. for each index i in <code>getOptionLabels</code>, i in
+	 * <code>getOptionValues()</code> should be the associated value.
+	 * 
+	 * <p>
+	 * For example, if an attribute can have the value male, female, unknown,
+	 * this list can return (for dutch)
+	 * <code>new String[] { "Man", "Vrouw", "Onbekend" }</code>.
+	 * 
+	 * @return A list values
+	 */
+	public String[] getOptionLabels();
+
+	/**
+	 * Validate an attribute in <code>String</code> form.
+	 * 
+	 * An attribute might be further constrained in value. This method will
+	 * attempt to validate the attribute according to these constraints. It can
+	 * return three different values:
+	 * 
+	 * <pre>
+	 *  null           No validation present
+	 *  ""             No problems detected
+	 *  "..."          A localized description of why the value is wrong
+	 * </pre>
+	 * 
+	 * @param value The value before turning it into the basic data type
+	 * @return <code>null</code>, "", or another string
+	 */
+	public String validate(String value);
+
+	/**
+	 * Return a default for this attribute.
+	 * 
+	 * The object must be of the appropriate type as defined by the cardinality
+	 * and <code>getType()</code>. The return type is a list of <code>String</code>
+	 * objects that can be converted to the appropriate type. The cardinality of
+	 * the return array must follow the absolute cardinality of this type. E.g.
+	 * if the cardinality = 0, the array must contain 1 element. If the
+	 * cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must
+	 * contain from 0 to max 5 elements. Note that the special case of a 0
+	 * cardinality, meaning a single value, does not allow arrays or vectors of
+	 * 0 elements.
+	 * 
+	 * @return Return a default value or <code>null</code> if no default exists.
+	 */
+	public String[] getDefaultValue();
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeInformation.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeInformation.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeInformation.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeInformation.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,52 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/MetaTypeInformation.java,v 1.8 2006/06/16 16:31:23 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.metatype;
+
+import org.osgi.framework.Bundle;
+
+/**
+ * A MetaType Information object is created by the MetaTypeService to return
+ * meta type information for a specific bundle.
+ * 
+ * @version $Revision: 1.8 $
+ * @since 1.1
+ */
+public interface MetaTypeInformation extends MetaTypeProvider {
+	/**
+	 * Return the PIDs (for ManagedServices) for which ObjectClassDefinition
+	 * information is available.
+	 * 
+	 * @return Array of PIDs.
+	 */
+	public String[] getPids();
+
+	/**
+	 * Return the Factory PIDs (for ManagedServiceFactories) for which
+	 * ObjectClassDefinition information is available.
+	 * 
+	 * @return Array of Factory PIDs.
+	 */
+	public String[] getFactoryPids();
+
+	/**
+	 * Return the bundle for which this object provides meta type information.
+	 * 
+	 * @return Bundle for which this object provides meta type information.
+	 */
+	public Bundle getBundle();
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeProvider.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeProvider.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeProvider.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeProvider.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,57 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/MetaTypeProvider.java,v 1.11 2006/06/16 16:31:23 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.metatype;
+
+/**
+ * Provides access to metatypes.
+ * 
+ * @version $Revision: 1.11 $
+ */
+public interface MetaTypeProvider {
+	/**
+	 * Returns an object class definition for the specified id localized to the
+	 * specified locale.
+	 * 
+	 * <p>
+	 * The locale parameter must be a name that consists of <code>language</code>[
+	 * "_" <code>country</code>[ "_" <code>variation</code>] ] as is customary in
+	 * the <code>Locale</code> class. This <code>Locale</code> class is not used
+	 * because certain profiles do not contain it.
+	 * 
+	 * @param id The ID of the requested object class. This can be a pid or
+	 *        factory pid returned by getPids or getFactoryPids.
+	 * @param locale The locale of the definition or <code>null</code> for default
+	 *        locale.
+	 * @return A <code>ObjectClassDefinition</code> object.
+	 * @throws IllegalArgumentException If the id or locale arguments are not
+	 *         valid
+	 */
+	public ObjectClassDefinition getObjectClassDefinition(String id, String locale);
+
+	/**
+	 * Return a list of available locales.
+	 * 
+	 * The results must be names that consists of language [ _ country [ _
+	 * variation ]] as is customary in the <code>Locale</code> class.
+	 * 
+	 * @return An array of locale strings or <code>null</code> if there is no
+	 *         locale specific localization can be found.
+	 *  
+	 */
+	public String[] getLocales();
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeService.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeService.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeService.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/MetaTypeService.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,53 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/MetaTypeService.java,v 1.10 2006/06/16 16:31:23 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.metatype;
+
+import org.osgi.framework.Bundle;
+
+/**
+ * The MetaType Service can be used to obtain meta type information for a
+ * bundle. The MetaType Service will examine the specified bundle for meta type
+ * documents to create the returned <code>MetaTypeInformation</code> object.
+ * 
+ * <p>
+ * If the specified bundle does not contain any meta type documents, then a
+ * <code>MetaTypeInformation</code> object will be returned that wrappers any
+ * <code>ManagedService</code> or <code>ManagedServiceFactory</code>
+ * services registered by the specified bundle that implement
+ * <code>MetaTypeProvider</code>. Thus the MetaType Service can be used to
+ * retrieve meta type information for bundles which contain a meta type
+ * documents or which provide their own <code>MetaTypeProvider</code> objects.
+ * 
+ * @version $Revision: 1.10 $
+ * @since 1.1
+ */
+public interface MetaTypeService {
+	/**
+	 * Return the MetaType information for the specified bundle.
+	 * 
+	 * @param bundle The bundle for which meta type information is requested.
+	 * @return A MetaTypeInformation object for the specified bundle.
+	 */
+	public MetaTypeInformation getMetaTypeInformation(Bundle bundle);
+
+	/**
+	 * Location of meta type documents. The MetaType Service will process each
+	 * entry in the meta type documents directory.
+	 */
+	public final static String	METATYPE_DOCUMENTS_LOCATION	= "OSGI-INF/metatype";
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/ObjectClassDefinition.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/ObjectClassDefinition.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/ObjectClassDefinition.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/ObjectClassDefinition.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,121 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/ObjectClassDefinition.java,v 1.11 2006/06/16 16:31:23 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.service.metatype;
+
+import java.io.IOException;
+import java.io.InputStream;
+
+/**
+ * Description for the data type information of an objectclass.
+ * 
+ * @version $Revision: 1.11 $
+ */
+public interface ObjectClassDefinition {
+	/**
+	 * Argument for <code>getAttributeDefinitions(int)</code>.
+	 * <p>
+	 * <code>REQUIRED</code> indicates that only the required definitions are
+	 * returned. The value is 1.
+	 */
+	public static final int	REQUIRED	= 1;
+	/**
+	 * Argument for <code>getAttributeDefinitions(int)</code>.
+	 * <p>
+	 * <code>OPTIONAL</code> indicates that only the optional definitions are
+	 * returned. The value is 2.
+	 */
+	public static final int	OPTIONAL	= 2;
+	/**
+	 * Argument for <code>getAttributeDefinitions(int)</code>.
+	 * <p>
+	 * <code>ALL</code> indicates that all the definitions are returned. The value
+	 * is -1.
+	 */
+	public static final int	ALL			= 0xFFFFFFFF;
+
+	/**
+	 * Return the name of this object class.
+	 * 
+	 * The name may be localized.
+	 * 
+	 * @return The name of this object class.
+	 */
+	public String getName();
+
+	/**
+	 * Return the id of this object class.
+	 * 
+	 * <p>
+	 * <code>ObjectDefintion</code> objects share a global namespace in the
+	 * registry. They share this aspect with LDAP/X.500 attributes. In these
+	 * standards the OSI Object Identifier (OID) is used to uniquely identify
+	 * object classes. If such an OID exists, (which can be requested at several
+	 * standard organisations and many companies already have a node in the
+	 * tree) it can be returned here. Otherwise, a unique id should be returned
+	 * which can be a java class name (reverse domain name) or generated with a
+	 * GUID algorithm. Note that all LDAP defined object classes already have an
+	 * OID associated. It is strongly advised to define the object classes from
+	 * existing LDAP schemes which will give the OID for free. Many such schemes
+	 * exist ranging from postal addresses to DHCP parameters.
+	 * 
+	 * @return The id of this object class.
+	 */
+	public String getID();
+
+	/**
+	 * Return a description of this object class.
+	 * 
+	 * The description may be localized.
+	 * 
+	 * @return The description of this object class.
+	 */
+	public String getDescription();
+
+	/**
+	 * Return the attribute definitions for this object class.
+	 * 
+	 * <p>
+	 * Return a set of attributes. The filter parameter can distinguish between
+	 * <code>ALL</code>,<code>REQUIRED</code> or the <code>OPTIONAL</code>
+	 * attributes.
+	 * 
+	 * @param filter <code>ALL</code>,<code>REQUIRED</code>,<code>OPTIONAL</code>
+	 * @return An array of attribute definitions or <code>null</code> if no
+	 *         attributes are selected
+	 */
+	public AttributeDefinition[] getAttributeDefinitions(int filter);
+
+	/**
+	 * Return an <code>InputStream</code> object that can be used to create an
+	 * icon from.
+	 * 
+	 * <p>
+	 * Indicate the size and return an <code>InputStream</code> object containing
+	 * an icon. The returned icon maybe larger or smaller than the indicated
+	 * size.
+	 * 
+	 * <p>
+	 * The icon may depend on the localization.
+	 * 
+	 * @param size Requested size of an icon, e.g. a 16x16 pixels icon then size =
+	 *        16
+	 * @return An InputStream representing an icon or <code>null</code>
+	 * @throws IOException If the <code>InputStream</code> cannot be returned.
+	 */
+	public InputStream getIcon(int size) throws IOException;
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/package.html
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/package.html?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/package.html (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/package.html Mon Jun  2 04:39:58 2008
@@ -0,0 +1 @@
+<!-- $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/package.html,v 1.5 2006/07/12 21:07:16 hargrave Exp $ -->
<BODY>
<p>Metatype Package Version 1.1.
<p>Bundles wishing to use this package must list the package
in the <TT>Import-Package</TT> header of the bundle's manifest.
For example:
<pre>
Import-Package: org.osgi.service.metatype; version=1.1
</pre>
</BODY>
\ No newline at end of file

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/packageinfo
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/packageinfo?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/packageinfo (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/metatype/packageinfo Mon Jun  2 04:39:58 2008
@@ -0,0 +1 @@
+version 1.1

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorAdmin.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorAdmin.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorAdmin.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorAdmin.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,359 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitorAdmin.java,v 1.25 2006/06/16 16:31:25 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 2006). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.monitor;
+
+/**
+ * The <code>MonitorAdmin</code> service is a singleton service that handles
+ * <code>StatusVariable</code> query requests and measurement job control
+ * requests.
+ * <p>
+ * Note that an alternative but not recommended way of obtaining
+ * <code>StatusVariable</code>s is that applications having the required
+ * <code>ServicePermissions</code> can query the list of
+ * <code>Monitorable</code> services from the service registry and then query
+ * the list of <code>StatusVariable</code> names from the
+ * <code>Monitorable</code> services. This way all services which publish
+ * <code>StatusVariable</code>s will be returned regardless of whether they
+ * do or do not hold the necessary <code>MonitorPermission</code> for
+ * publishing <code>StatusVariable</code>s. By using the
+ * <code>MonitorAdmin</code> to obtain the <code>StatusVariable</code>s it
+ * is guaranteed that only those <code>Monitorable</code> services will be
+ * accessed who are authorized to publish <code>StatusVariable</code>s. It is
+ * the responsibility of the <code>MonitorAdmin</code> implementation to check
+ * the required permissions and show only those variables which pass this check.
+ * <p>
+ * The events posted by <code>MonitorAdmin</code> contain the following
+ * properties:
+ * <ul>
+ * <li><code>mon.monitorable.pid</code>: The identifier of the
+ * <code>Monitorable</code>
+ * <li><code>mon.statusvariable.name</code>: The identifier of the
+ * <code>StatusVariable</code> within the given <code>Monitorable</code>
+ * <li><code>mon.statusvariable.value</code>: The value of the
+ * <code>StatusVariable</code>, represented as a <code>String</code>
+ * <li><code>mon.listener.id</code>: The identifier of the initiator of the
+ * monitoring job (only present if the event was generated due to a monitoring
+ * job)
+ * </ul>
+ * <p>
+ * Most of the methods require either a Monitorable ID or a Status Variable path
+ * parameter, the latter in [Monitorable_ID]/[StatusVariable_ID] format.  These
+ * parameters must not be <code>null</code>, and the IDs they contain must
+ * conform to their respective definitions in {@link Monitorable} and
+ * {@link StatusVariable}.  If any of the restrictions are violated, the method
+ * must throw an <code>IllegalArgumentException</code>.
+ */
+public interface MonitorAdmin {
+
+    /**
+     * Returns a <code>StatusVariable</code> addressed by its full path. 
+     * The entity which queries a <code>StatusVariable</code> needs to hold
+     * <code>MonitorPermission</code> for the given target with the
+     * <code>read</code> action present.
+     * 
+     * @param path the full path of the <code>StatusVariable</code> in
+     *        [Monitorable_ID]/[StatusVariable_ID] format
+     * @return the <code>StatusVariable</code> object
+     * @throws java.lang.IllegalArgumentException if <code>path</code> is
+     *         <code>null</code> or otherwise invalid, or points to a
+     *         non-existing <code>StatusVariable</code>
+     * @throws java.lang.SecurityException if the caller does not hold a
+     *         <code>MonitorPermission</code> for the
+     *         <code>StatusVariable</code> specified by <code>path</code>
+     *         with the <code>read</code> action present
+     */
+    public StatusVariable getStatusVariable(String path)
+            throws IllegalArgumentException, SecurityException;
+
+    /**
+     * Returns the names of the <code>Monitorable</code> services that are
+     * currently registered. The <code>Monitorable</code> instances are not
+     * accessible through the <code>MonitorAdmin</code>, so that requests to
+     * individual status variables can be filtered with respect to the
+     * publishing rights of the <code>Monitorable</code> and the reading
+     * rights of the caller.
+     * <p>
+     * The returned array contains the names in alphabetical order. It cannot be
+     * <code>null</code>, an empty array is returned if no
+     * <code>Monitorable</code> services are registered.
+     * 
+     * @return the array of <code>Monitorable</code> names
+     */
+    public String[] getMonitorableNames();
+
+    /**
+     * Returns the <code>StatusVariable</code> objects published by a
+     * <code>Monitorable</code> instance. The <code>StatusVariables</code>
+     * will hold the values taken at the time of this method call. Only those
+     * status variables are returned where the following two conditions are met:
+     * <ul>
+     * <li>the specified <code>Monitorable</code> holds a
+     * <code>MonitorPermission</code> for the status variable with the
+     * <code>publish</code> action present
+     * <li>the caller holds a <code>MonitorPermission</code> for the status
+     * variable with the <code>read</code> action present
+     * </ul>
+     * All other status variables are silently ignored, they are omitted from
+     * the result.
+     * <p>
+     * The elements in the returned array are in no particular order. The return
+     * value cannot be <code>null</code>, an empty array is returned if no 
+     * (authorized and readable) Status Variables are provided by the given 
+     * <code>Monitorable</code>.
+     * 
+     * @param monitorableId the identifier of a <code>Monitorable</code>
+     *        instance
+     * @return a list of <code>StatusVariable</code> objects published
+     *         by the specified <code>Monitorable</code>
+     * @throws java.lang.IllegalArgumentException if <code>monitorableId</code>
+     *         is <code>null</code> or otherwise invalid, or points to a
+     *         non-existing <code>Monitorable</code>
+     */
+    public StatusVariable[] getStatusVariables(String monitorableId)
+            throws IllegalArgumentException;
+
+    /**
+     * Returns the list of <code>StatusVariable</code> names published by a
+     * <code>Monitorable</code> instance. Only those status variables are
+     * listed where the following two conditions are met:
+     * <ul>
+     * <li>the specified <code>Monitorable</code> holds a
+     * <code>MonitorPermission</code> for the status variable with the
+     * <code>publish</code> action present
+     * <li>the caller holds a <code>MonitorPermission</code> for
+     * the status variable with the <code>read</code> action present
+     * </ul>
+     * All other status variables are silently ignored, their names are omitted
+     * from the list.
+     * <p>
+     * The returned array does not contain duplicates, and the elements are in 
+     * alphabetical order. It cannot be <code>null</code>, an empty array is 
+     * returned if no (authorized and readable) Status Variables are provided 
+     * by the given <code>Monitorable</code>.
+     * 
+     * @param monitorableId the identifier of a <code>Monitorable</code>
+     *        instance
+     * @return a list of <code>StatusVariable</code> objects names
+     *         published by the specified <code>Monitorable</code>
+     * @throws java.lang.IllegalArgumentException if <code>monitorableId</code>
+     *         is <code>null</code> or otherwise invalid, or points to a
+     *         non-existing <code>Monitorable</code>
+     */
+    public String[] getStatusVariableNames(String monitorableId)
+            throws IllegalArgumentException;
+
+    /**
+     * Switches event sending on or off for the specified 
+     * <code>StatusVariable</code>s. When the <code>MonitorAdmin</code> is
+     * notified about a <code>StatusVariable</code> being updated it sends an
+     * event unless this feature is switched off. Note that events within a
+     * monitoring job can not be switched off. The event sending state of the 
+     * <code>StatusVariables</code> must not be persistently stored. When a 
+     * <code>StatusVariable</code> is registered for the first time in a 
+     * framework session, its event sending state is set to ON by default.
+     * <p>
+     * Usage of the "*" wildcard is allowed in the path argument of this method
+     * as a convenience feature. The wildcard can be used in either or both path
+     * fragments, but only at the end of the fragments.  The semantics of the 
+     * wildcard is that it stands for any matching <code>StatusVariable</code> 
+     * at the time of the method call, it does not affect the event sending 
+     * status of <code>StatusVariable</code>s which are not yet registered. As 
+     * an example, when the <code>switchEvents("MyMonitorable/*", false)</code>
+     * method is executed, event sending from all <code>StatusVariables</code>
+     * of the MyMonitorable service are switched off. However, if the
+     * MyMonitorable service starts to publish a new <code>StatusVariable</code>
+     * later, it's event sending status is on by default.
+     * 
+     * @param path the identifier of the <code>StatusVariable</code>(s) in
+     *        [Monitorable_id]/[StatusVariable_id] format, possibly with the 
+     *        "*" wildcard at the end of either path fragment
+     * @param on <code>false</code> if event sending should be switched off, 
+     *        <code>true</code> if it should be switched on for the given path
+     * @throws java.lang.SecurityException if the caller does not hold
+     *         <code>MonitorPermission</code> with the
+     *         <code>switchevents</code> action or if there is any
+     *         <code>StatusVariable</code> in the <code>path</code> field for
+     *         which it is not allowed to switch event sending on or off as per 
+     *         the target field of the permission
+     * @throws java.lang.IllegalArgumentException if <code>path</code> is 
+     *         <code>null</code> or otherwise invalid, or points to a 
+     *         non-existing <code>StatusVariable</code>
+     */
+    public void switchEvents(String path, boolean on)
+        throws IllegalArgumentException, SecurityException;
+    
+    /**
+     * Issues a request to reset a given <code>StatusVariable</code>.
+     * Depending on the semantics of the <code>StatusVariable</code> this call
+     * may or may not succeed: it makes sense to reset a counter to its starting
+     * value, but e.g. a <code>StatusVariable</code> of type String might not
+     * have a meaningful default value. Note that for numeric
+     * <code>StatusVariable</code>s the starting value may not necessarily be
+     * 0. Resetting a <code>StatusVariable</code> triggers a monitor event if
+     * the <code>StatusVariable</code> supports update notifications.
+     * <p>
+     * The entity that wants to reset the <code>StatusVariable</code> needs to
+     * hold <code>MonitorPermission</code> with the <code>reset</code>
+     * action present. The target field of the permission must match the
+     * <code>StatusVariable</code> name to be reset.
+     * 
+     * @param path the identifier of the <code>StatusVariable</code> in
+     *        [Monitorable_id]/[StatusVariable_id] format
+     * @return <code>true</code> if the <code>Monitorable</code> could
+     *         successfully reset the given <code>StatusVariable</code>,
+     *         <code>false</code> otherwise
+     * @throws java.lang.IllegalArgumentException if <code>path</code> is 
+     *         <code>null</code> or otherwise invalid, or points to a 
+     *         non-existing <code>StatusVariable</code>
+     * @throws java.lang.SecurityException if the caller does not hold
+     *         <code>MonitorPermission</code> with the <code>reset</code>
+     *         action or if the specified <code>StatusVariable</code> is not
+     *         allowed to be reset as per the target field of the permission
+     */
+    public boolean resetStatusVariable(String path)
+            throws IllegalArgumentException, SecurityException;
+    
+    /**
+     * Returns a human readable description of the given 
+     * <code>StatusVariable</code>. The <code>null</code> value may be returned
+     * if there is no description for the given <code>StatusVariable</code>.
+     * <p>
+     * The entity that queries a <code>StatusVariable</code> needs to hold
+     * <code>MonitorPermission</code> for the given target with the
+     * <code>read</code> action present.
+     * 
+     * @param path the full path of the <code>StatusVariable</code> in
+     *        [Monitorable_ID]/[StatusVariable_ID] format
+     * @return the human readable description of this
+     *         <code>StatusVariable</code> or <code>null</code> if it is not
+     *         set
+     * @throws java.lang.IllegalArgumentException if <code>path</code> is 
+     *         <code>null</code> or otherwise invalid, or points to a 
+     *         non-existing <code>StatusVariable</code>
+     * @throws java.lang.SecurityException if the caller does not hold a
+     *         <code>MonitorPermission</code> for the
+     *         <code>StatusVariable</code> specified by <code>path</code>
+     *         with the <code>read</code> action present
+     */
+    public String getDescription(String path) 
+            throws IllegalArgumentException, SecurityException;
+
+    /**
+     * Starts a time based <code>MonitoringJob</code> with the parameters
+     * provided. Monitoring events will be sent according to the specified
+     * schedule. All specified <code>StatusVariable</code>s must exist when the
+     * job is started. The initiator string is used in the
+     * <code>mon.listener.id</code> field of all events triggered by the job,
+     * to allow filtering the events based on the initiator.
+     * <p>
+     * The <code>schedule</code> parameter specifies the time in seconds 
+     * between two measurements, it must be greater than 0.  The first 
+     * measurement will be taken when the timer expires for the first time, not 
+     * when this method is called.
+     * <p>
+     * The <code>count</code> parameter defines the number of measurements to be
+     * taken, and must either be a positive integer, or 0 if the measurement is
+     * to run until explicitely stopped.
+     * <p>
+     * The entity which initiates a <code>MonitoringJob</code> needs to hold
+     * <code>MonitorPermission</code> for all the specified target
+     * <code>StatusVariable</code>s with the <code>startjob</code> action
+     * present. If the permission's action string specifies a minimal sampling
+     * interval then the <code>schedule</code> parameter should be at least as
+     * great as the value in the action string.
+     * 
+     * @param initiator the identifier of the entity that initiated the job
+     * @param statusVariables the list of <code>StatusVariable</code>s to be
+     *        monitored, with each <code>StatusVariable</code> name given in
+     *        [Monitorable_PID]/[StatusVariable_ID] format
+     * @param schedule the time in seconds between two measurements
+     * @param count the number of measurements to be taken, or 0 for the
+     *        measurement to run until explicitely stopped
+     * @return the successfully started job object, cannot be <code>null</code>
+     * @throws java.lang.IllegalArgumentException if the list of
+     *         <code>StatusVariable</code> names contains an invalid or 
+     *         non-existing <code>StatusVariable</code>; if 
+     *         <code>initiator</code> is <code>null</code> or empty; or if the 
+     *         <code>schedule</code> or <code>count</code> parameters are 
+     *         invalid
+     * @throws java.lang.SecurityException if the caller does not hold
+     *         <code>MonitorPermission</code> for all the specified
+     *         <code>StatusVariable</code>s, with the <code>startjob</code>
+     *         action present, or if the permission does not allow starting the
+     *         job with the given frequency
+     */
+    public MonitoringJob startScheduledJob(String initiator,
+            String[] statusVariables, int schedule, int count)
+            throws IllegalArgumentException, SecurityException;
+
+    /**
+     * Starts a change based <code>MonitoringJob</code> with the parameters
+     * provided. Monitoring events will be sent when the
+     * <code>StatusVariable</code>s of this job are updated. All specified
+     * <code>StatusVariable</code>s must exist when the job is started, and
+     * all must support update notifications. The initiator string is used in
+     * the <code>mon.listener.id</code> field of all events triggered by the
+     * job, to allow filtering the events based on the initiator.
+     * <p>
+     * The <code>count</code> parameter specifies the number of changes that
+     * must happen to a <code>StatusVariable</code> before a new notification is
+     * sent, this must be a positive integer.
+     * <p>
+     * The entity which initiates a <code>MonitoringJob</code> needs to hold
+     * <code>MonitorPermission</code> for all the specified target
+     * <code>StatusVariable</code>s with the <code>startjob</code> action
+     * present.
+     * 
+     * @param initiator the identifier of the entity that initiated the job
+     * @param statusVariables the list of <code>StatusVariable</code>s to be
+     *        monitored, with each <code>StatusVariable</code> name given in
+     *        [Monitorable_PID]/[StatusVariable_ID] format
+     * @param count the number of changes that must happen to a 
+     *        <code>StatusVariable</code> before a new notification is sent
+     * @return the successfully started job object, cannot be <code>null</code>
+     * @throws java.lang.IllegalArgumentException if the list of
+     *         <code>StatusVariable</code> names contains an invalid or 
+     *         non-existing <code>StatusVariable</code>, or one that does not 
+     *         support notifications; if the <code>initiator</code> is 
+     *         <code>null</code> or empty; or if <code>count</code> is invalid
+     * @throws java.lang.SecurityException if the caller does not hold
+     *         <code>MonitorPermission</code> for all the specified
+     *         <code>StatusVariable</code>s, with the <code>startjob</code>
+     *         action present
+     */
+    public MonitoringJob startJob(String initiator, String[] statusVariables,
+            int count) throws IllegalArgumentException, SecurityException;
+
+    /**
+     * Returns the list of currently running <code>MonitoringJob</code>s.
+     * Jobs are only visible to callers that have the necessary permissions: to 
+     * receive a Monitoring Job in the returned list, the caller must hold all 
+     * permissions required for starting the job.  This means that if the caller
+     * does not have <code>MonitorPermission</code> with the proper
+     * <code>startjob</code> action for all the Status Variables monitored by a 
+     * job, then that job will be silently omitted from the results.
+     * <p>
+     * The returned array cannot be <code>null</code>, an empty array is
+     * returned if there are no running jobs visible to the caller at the time 
+     * of the call.
+     * 
+     * @return the list of running jobs visible to the caller
+     */
+    public MonitoringJob[] getRunningJobs();
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorListener.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorListener.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorListener.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorListener.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,42 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitorListener.java,v 1.11 2006/06/16 16:31:25 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.monitor;
+
+/**
+ * The <code>MonitorListener</code> is used by <code>Monitorable</code>
+ * services to send notifications when a <code>StatusVariable</code> value is
+ * changed. The <code>MonitorListener</code> should register itself as a
+ * service at the OSGi Service Registry. This interface must (only) be 
+ * implemented by the Monitor Admin component.
+ */
+public interface MonitorListener {
+    /**
+     * Callback for notification of a <code>StatusVariable</code> change.
+     * 
+     * @param monitorableId the identifier of the <code>Monitorable</code>
+     *        instance reporting the change
+     * @param statusVariable the <code>StatusVariable</code> that has changed
+     * @throws java.lang.IllegalArgumentException if the specified monitorable
+     *         ID is invalid (<code>null</code>, empty, or contains illegal
+     *         characters) or points to a non-existing <code>Monitorable</code>, 
+     *         or if <code>statusVariable</code> is <code>null</code>
+     */
+    public void updated(String monitorableId, StatusVariable statusVariable)
+            throws IllegalArgumentException;
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorPermission.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorPermission.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorPermission.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitorPermission.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,366 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitorPermission.java,v 1.17 2006/06/21 15:17:16 hargrave Exp $
+ * 
+ * Copyright (c) OSGi Alliance (2005, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.monitor;
+
+import java.io.UnsupportedEncodingException;
+import java.security.Permission;
+import java.util.StringTokenizer;
+
+/**
+ * Indicates the callers authority to publish, read or reset
+ * <code>StatusVariable</code>s, to switch event sending on or off or to
+ * start monitoring jobs. The target of the permission is the identifier of the
+ * <code>StatusVariable</code>, the action can be <code>read</code>,
+ * <code>publish</code>, <code>reset</code>, <code>startjob</code>,
+ * <code>switchevents</code>, or the combination of these separated by
+ * commas.  Action names are interpreted case-insensitively, but the canonical 
+ * action string returned by {@link #getActions} uses the forms defined by the 
+ * action constants.
+ * <p>
+ * If the wildcard <code>*</code> appears in the actions field, all legal 
+ * monitoring commands are allowed on the designated target(s) by the owner of 
+ * the permission.
+ */
+public class MonitorPermission extends Permission {
+
+    /**
+	 * 
+	 */
+	private static final long	serialVersionUID	= -9084425194463274314L;
+
+	/**
+     * Holders of <code>MonitorPermission</code> with the <code>read</code>
+     * action present are allowed to read the value of the
+     * <code>StatusVariable</code>s specified in the permission's target field.
+     */
+    public static final String READ = "read";
+
+    /**
+     * Holders of <code>MonitorPermission</code> with the <code>reset</code>
+     * action present are allowed to reset the value of the
+     * <code>StatusVariable</code>s specified in the permission's target field.
+     */
+    public static final String RESET = "reset";
+
+    /**
+     * Holders of <code>MonitorPermission</code> with the <code>publish</code>
+     * action present are <code>Monitorable</code> services that are allowed
+     * to publish the <code>StatusVariable</code>s specified in the
+     * permission's target field.  Note, that this permission cannot be enforced 
+     * when a <code>Monitorable</code> registers to the framework, because the
+     * Service Registry does not know about this permission.  Instead, any
+     * <code>StatusVariable</code>s published by a <code>Monitorable</code>
+     * without the corresponding <code>publish</code> permission are silently
+     * ignored by <code>MonitorAdmin</code>, and are therefore invisible to the
+     * users of the monitoring service.   
+     */
+    public static final String PUBLISH = "publish";
+
+    /**
+     * Holders of <code>MonitorPermission</code> with the <code>startjob</code>
+     * action present are allowed to initiate monitoring jobs involving the 
+     * <code>StatusVariable</code>s specified in the permission's target field.
+     * <p>
+     * A minimal sampling interval can be optionally defined in the following
+     * form: <code>startjob:n</code>.  This allows the holder of the permission
+     * to initiate time based jobs with a measurement interval of at least
+     * <code>n</code> seconds. If <code>n</code> is not specified or 0 then the 
+     * holder of this permission is allowed to start monitoring jobs specifying 
+     * any frequency.
+     */
+    public static final String STARTJOB = "startjob";
+
+    /**
+     * Holders of <code>MonitorPermission</code> with the
+     * <code>switchevents</code> action present are allowed to switch event
+     * sending on or off for the value of the <code>StatusVariable</code>s
+     * specified in the permission's target field.
+     */
+    public static final String SWITCHEVENTS = "switchevents";
+
+    private static final int READ_FLAG         = 0x1;
+    private static final int RESET_FLAG        = 0x2;
+    private static final int PUBLISH_FLAG      = 0x4;
+    private static final int STARTJOB_FLAG     = 0x8;
+    private static final int SWITCHEVENTS_FLAG = 0x10;
+    
+    private static final int ALL_FLAGS = READ_FLAG | RESET_FLAG | 
+        PUBLISH_FLAG | STARTJOB_FLAG | SWITCHEVENTS_FLAG;
+
+    private String monId;
+    private String varId;
+    private boolean prefixMonId;
+    private boolean prefixVarId;
+    private int mask;
+    private int minJobInterval;
+
+    /**
+     * Create a <code>MonitorPermission</code> object, specifying the target
+     * and actions.
+     * <p>
+     * The <code>statusVariable</code> parameter is the target of the 
+     * permission, defining one or more status variable names to which the
+     * specified actions apply. Multiple status variable names can be selected
+     * by using the wildcard <code>*</code> in the target string.  The wildcard
+     * is allowed in both fragments, but only at the end of the fragments.
+     * <p>
+     * For example, the following targets are valid:
+     * <code>com.mycomp.myapp/queue_length</code>,
+     * <code>com.mycomp.myapp/*</code>, <code>com.mycomp.&#42;/*</code>,
+     * <code>&#42;/*</code>, <code>&#42;/queue_length</code>, 
+     * <code>&#42;/queue*</code>.
+     * <p>
+     * The following targets are invalid:
+     * <code>*.myapp/queue_length</code>, <code>com.*.myapp/*</code>,
+     * <code>*</code>.
+     * <p>
+     * The <code>actions</code> parameter specifies the allowed action(s): 
+     * <code>read</code>, <code>publish</code>, <code>startjob</code>,
+     * <code>reset</code>, <code>switchevents</code>, or the combination of 
+     * these separated by commas. String constants are defined in this class for
+     * each valid action.  Passing <code>&quot;*&quot;</code> as the action 
+     * string is equivalent to listing all actions. 
+     * 
+     * @param statusVariable the identifier of the <code>StatusVariable</code>
+     *        in [Monitorable_id]/[StatusVariable_id] format 
+     * @param actions the list of allowed actions separated by commas, or
+     *        <code>*</code> for all actions
+     * @throws java.lang.IllegalArgumentException if either parameter is 
+     *         <code>null</code>, or invalid with regard to the constraints
+     *         defined above and in the documentation of the used actions 
+     */
+    public MonitorPermission(String statusVariable, String actions) 
+            throws IllegalArgumentException {
+        super(statusVariable);
+
+        if(statusVariable == null)
+            throw new IllegalArgumentException(
+                    "Invalid StatusVariable path 'null'.");
+        
+        if(actions == null)
+            throw new IllegalArgumentException(
+                    "Invalid actions string 'null'.");
+        
+        int sep = statusVariable.indexOf('/');
+        int len = statusVariable.length();
+
+        if (sep == -1)
+            throw new IllegalArgumentException(
+                    "Invalid StatusVariable path: should contain '/' separator.");
+        if (sep == 0 || sep == statusVariable.length() - 1)
+            throw new IllegalArgumentException(
+                    "Invalid StatusVariable path: empty monitorable ID or StatusVariable name.");
+
+        prefixMonId = statusVariable.charAt(sep - 1) == '*';
+        prefixVarId = statusVariable.charAt(len - 1) == '*';
+        
+        monId = statusVariable.substring(0, prefixMonId ? sep - 1 : sep);
+        varId = statusVariable.substring(sep + 1, prefixVarId ? len - 1 : len);
+
+        checkId(monId, "Monitorable ID part of the target");
+        checkId(varId, "Status Variable ID part of the target");
+
+        minJobInterval = 0;
+
+        if(actions.equals("*"))
+            mask = ALL_FLAGS;
+        else {
+            mask = 0;
+            StringTokenizer st = new StringTokenizer(actions, ",");
+            while (st.hasMoreTokens()) {
+                String action = st.nextToken();
+                if (action.equalsIgnoreCase(READ)) {
+                    addToMask(READ_FLAG, READ);
+                } else if (action.equalsIgnoreCase(RESET)) {
+                    addToMask(RESET_FLAG, RESET);
+                } else if (action.equalsIgnoreCase(PUBLISH)) {
+                    addToMask(PUBLISH_FLAG, PUBLISH);
+                } else if (action.equalsIgnoreCase(SWITCHEVENTS)) {
+                    addToMask(SWITCHEVENTS_FLAG, SWITCHEVENTS);
+                } else if (action.toLowerCase().startsWith(STARTJOB)) {
+                    minJobInterval = 0;
+    
+                    int slen = STARTJOB.length();
+                    if (action.length() != slen) {
+                        if (action.charAt(slen) != ':')
+                            throw new IllegalArgumentException(
+                                    "Invalid action '" + action + "'.");
+    
+                        try {
+                            minJobInterval = Integer.parseInt(action
+                                    .substring(slen + 1));
+                        } catch (NumberFormatException e) {
+                            throw new IllegalArgumentException(
+                                    "Invalid parameter in startjob action '"
+                                            + action + "'.");
+                        }
+                    }
+                    addToMask(STARTJOB_FLAG, STARTJOB);
+                } else
+                    throw new IllegalArgumentException("Invalid action '" + 
+                            action + "'");
+            }
+        }
+    }
+    
+    private void addToMask(int action, String actionString) {
+        if((mask & action) != 0)
+            throw new IllegalArgumentException("Invalid action string: " + 
+                    actionString + " appears multiple times.");
+        
+        mask |= action;
+    }
+
+    private void checkId(String id, String idName)
+            throws IllegalArgumentException {
+        
+        byte[] nameBytes;
+        try {
+            nameBytes = id.getBytes("UTF-8");
+        } catch (UnsupportedEncodingException e) {
+            // never happens, "UTF-8" must always be supported
+            throw new IllegalStateException(e.getMessage());
+        }
+        if(nameBytes.length > StatusVariable.MAX_ID_LENGTH)
+            throw new IllegalArgumentException(idName + " is too long (over " +
+                    StatusVariable.MAX_ID_LENGTH + " bytes in UTF-8 encoding).");
+
+        
+        if (id.equals(".") || id.equals(".."))
+            throw new IllegalArgumentException(idName + " is invalid.");
+        
+        char[] chars = id.toCharArray();
+        for (int i = 0; i < chars.length; i++)
+            if (StatusVariable.SYMBOLIC_NAME_CHARACTERS.indexOf(chars[i]) == -1)
+                throw new IllegalArgumentException(idName +
+                        " contains invalid characters.");
+    }
+    
+    /**
+     * Create an integer hash of the object. The hash codes of
+     * <code>MonitorPermission</code>s <code>p1</code> and <code>p2</code> are 
+     * the same if <code>p1.equals(p2)</code>.
+     * 
+     * @return the hash of the object
+     */
+    public int hashCode() {
+        return new Integer(mask).hashCode()
+                ^ new Integer(minJobInterval).hashCode() ^ monId.hashCode()
+                ^ new Boolean(prefixMonId).hashCode()
+                ^ varId.hashCode()
+                ^ new Boolean(prefixVarId).hashCode();
+    }
+
+    /**
+     * Determines the equality of two <code>MonitorPermission</code> objects.
+     * Two <code>MonitorPermission</code> objects are equal if their target
+     * strings are equal and the same set of actions are listed in their action
+     * strings.
+     * 
+     * @param o the object being compared for equality with this object
+     * @return <code>true</code> if the two permissions are equal
+     */
+    public boolean equals(Object o) {
+        if (!(o instanceof MonitorPermission))
+            return false;
+
+        MonitorPermission other = (MonitorPermission) o;
+
+        return mask == other.mask && minJobInterval == other.minJobInterval
+                && monId.equals(other.monId)
+                && prefixMonId == other.prefixMonId
+                && varId.equals(other.varId)
+                && prefixVarId == other.prefixVarId;
+    }
+
+    /**
+     * Get the action string associated with this permission.  The actions are
+     * returned in the following order: <code>read</code>, <code>reset</code>, 
+     * <code>publish</code>, <code>startjob</code>, <code>switchevents</code>.
+     * 
+     * @return the allowed actions separated by commas, cannot be
+     *         <code>null</code>
+     */
+    public String getActions() {
+        StringBuffer sb = new StringBuffer();
+
+        appendAction(sb, READ_FLAG,         READ);
+        appendAction(sb, RESET_FLAG,        RESET);
+        appendAction(sb, PUBLISH_FLAG,      PUBLISH);
+        appendAction(sb, STARTJOB_FLAG,     STARTJOB);
+        appendAction(sb, SWITCHEVENTS_FLAG, SWITCHEVENTS);
+
+        return sb.toString();
+    }
+
+    private void appendAction(StringBuffer sb, int flag, String actionName) {
+        if ((mask & flag) != 0) {
+            if(sb.length() != 0)
+                sb.append(',');
+            sb.append(actionName);
+            
+            if(flag == STARTJOB_FLAG && minJobInterval != 0)
+                sb.append(':').append(minJobInterval);
+        }
+    }
+
+    /**
+     * Determines if the specified permission is implied by this permission.
+     * <p>
+     * This method returns <code>false</code> if and only if at least one of the
+     * following conditions are fulfilled for the specified permission:
+     * <ul>
+     * <li>it is not a <code>MonitorPermission</code>
+     * <li>it has a broader set of actions allowed than this one
+     * <li>it allows initiating time based monitoring jobs with a lower minimal
+     * sampling interval
+     * <li>the target set of <code>Monitorable</code>s is not the same nor a
+     * subset of the target set of <code>Monitorable</code>s of this permission
+     * <li>the target set of <code>StatusVariable</code>s is not the same
+     * nor a subset of the target set of <code>StatusVariable</code>s of this
+     * permission
+     * </ul>
+     * 
+     * @param p the permission to be checked
+     * @return <code>true</code> if the given permission is implied by this
+     *         permission
+     */
+    public boolean implies(Permission p) {
+        if (!(p instanceof MonitorPermission))
+            return false;
+
+        MonitorPermission other = (MonitorPermission) p;
+
+        if ((mask & other.mask) != other.mask)
+            return false;
+
+        if ((other.mask & STARTJOB_FLAG) != 0
+                && minJobInterval > other.minJobInterval)
+            return false;
+
+        return implies(monId, prefixMonId, other.monId, other.prefixMonId)
+                && implies(varId, prefixVarId, other.varId, other.prefixVarId);
+    }
+
+    private boolean implies(String id, boolean prefix, String oid,
+            boolean oprefix) {
+
+        return prefix ? oid.startsWith(id) : !oprefix && id.equals(oid);
+    }
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/Monitorable.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/Monitorable.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/Monitorable.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/Monitorable.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,140 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/Monitorable.java,v 1.17 2006/06/16 16:31:25 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.monitor;
+
+/**
+ * A <code>Monitorable</code> can provide information about itself in the form
+ * of <code>StatusVariables</code>. Instances of this interface should
+ * register themselves at the OSGi Service Registry. The
+ * <code>MonitorAdmin</code> listens to the registration of
+ * <code>Monitorable</code> services, and makes the information they provide
+ * available also through the Device Management Tree (DMT) for remote access.
+ * <p>
+ * The monitorable service is identified by its PID string which must be a non-
+ * <code>null</code>, non-empty string that conforms to the "symbolic-name"
+ * definition in the OSGi core specification. This means that only the
+ * characters [-_.a-zA-Z0-9] may be used. The length of the PID must not exceed
+ * 20 characters.
+ * <p>
+ * A <code>Monitorable</code> may optionally support sending notifications
+ * when the status of its <code>StatusVariables</code> change. Support for
+ * change notifications can be defined per <code>StatusVariable</code>.
+ * <p>
+ * Publishing <code>StatusVariables</code> requires the presence of the
+ * <code>MonitorPermission</code> with the <code>publish</code> action
+ * string. This permission, however, is not checked during registration of the
+ * <code>Monitorable</code> service. Instead, the <code>MonitorAdmin</code>
+ * implemenatation must make sure that when a <code>StatusVariable</code> is
+ * queried, it is shown only if the <code>Monitorable</code> is authorized to
+ * publish the given <code>StatusVariable</code>.
+ */
+public interface Monitorable {
+    /**
+     * Returns the list of <code>StatusVariable</code> identifiers published
+     * by this <code>Monitorable</code>. A <code>StatusVariable</code> name
+     * is unique within the scope of a <code>Monitorable</code>. The array
+     * contains the elements in no particular order. The returned value must not
+     * be <code>null</code>.
+     * 
+     * @return the <code>StatusVariable<code> identifiers published by this 
+     *         object, or an empty array if none are published
+     */
+    public String[] getStatusVariableNames();
+    
+    /**
+     * Returns the <code>StatusVariable</code> object addressed by its
+     * identifier. The <code>StatusVariable</code> will hold the value taken
+     * at the time of this method call.
+     * <p>
+     * The given identifier does not contain the Monitorable PID, i.e. it 
+     * specifies the name and not the path of the Status Variable.
+     * 
+     * @param id the identifier of the <code>StatusVariable</code>, cannot be
+     *        <code>null</code> 
+     * @return the <code>StatusVariable</code> object
+     * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+     *         non-existing <code>StatusVariable</code>
+     */
+    public StatusVariable getStatusVariable(String id)
+            throws IllegalArgumentException;
+
+    /**
+     * Tells whether the <code>StatusVariable</code> provider is able to send
+     * instant notifications when the given <code>StatusVariable</code>
+     * changes. If the <code>Monitorable</code> supports sending change
+     * updates it must notify the <code>MonitorListener</code> when the value
+     * of the <code>StatusVariable</code> changes. The
+     * <code>Monitorable</code> finds the <code>MonitorListener</code>
+     * service through the Service Registry.
+     * <p>
+     * The given identifier does not contain the Monitorable PID, i.e. it 
+     * specifies the name and not the path of the Status Variable.
+     * 
+     * @param id the identifier of the <code>StatusVariable</code>, cannot be
+     *        <code>null</code> 
+     * @return <code>true</code> if the <code>Monitorable</code> can send
+     *         notification when the given <code>StatusVariable</code>
+     *         changes, <code>false</code> otherwise
+     * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+     *         non-existing <code>StatusVariable</code>
+     */
+    public boolean notifiesOnChange(String id) throws IllegalArgumentException;
+
+    /**
+     * Issues a request to reset a given <code>StatusVariable</code>.
+     * Depending on the semantics of the actual Status Variable this call may or
+     * may not succeed: it makes sense to reset a counter to its starting value,
+     * but for example a <code>StatusVariable</code> of type <code>String</code>
+     * might not have a meaningful default value. Note that for numeric
+     * <code>StatusVariables</code> the starting value may not necessarily be
+     * 0. Resetting a <code>StatusVariable</code> must trigger a monitor event.
+     * <p>
+     * The given identifier does not contain the Monitorable PID, i.e. it 
+     * specifies the name and not the path of the Status Variable.
+     * 
+     * @param id the identifier of the <code>StatusVariable</code>, cannot be
+     *        <code>null</code> 
+     * @return <code>true</code> if the <code>Monitorable</code> could
+     *         successfully reset the given <code>StatusVariable</code>,
+     *         <code>false</code> otherwise
+     * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+     *         non-existing <code>StatusVariable</code>
+     */
+    public boolean resetStatusVariable(String id)
+            throws IllegalArgumentException;
+    
+    /**
+     * Returns a human readable description of a <code>StatusVariable</code>.
+     * This can be used by management systems on their GUI. The 
+     * <code>null</code> return value is allowed if there is no description for
+     * the specified Status Variable.
+     * <p>
+     * The given identifier does not contain the Monitorable PID, i.e. it 
+     * specifies the name and not the path of the Status Variable.
+     * 
+     * @param id the identifier of the <code>StatusVariable</code>, cannot be
+     *        <code>null</code> 
+     * @return the human readable description of this
+     *         <code>StatusVariable</code> or <code>null</code> if it is not
+     *         set
+     * @throws java.lang.IllegalArgumentException if <code>id</code> points to a
+     *         non-existing <code>StatusVariable</code>
+     */
+    public String getDescription(String id) throws IllegalArgumentException;
+}

Added: felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitoringJob.java
URL: http://svn.apache.org/viewvc/felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitoringJob.java?rev=662399&view=auto
==============================================================================
--- felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitoringJob.java (added)
+++ felix/trunk/deploymentadmin/service/src/main/java/org/osgi/service/monitor/MonitoringJob.java Mon Jun  2 04:39:58 2008
@@ -0,0 +1,126 @@
+/*
+ * $Header: /cvshome/build/org.osgi.service.monitor/src/org/osgi/service/monitor/MonitoringJob.java,v 1.14 2006/06/16 16:31:25 hargrave Exp $
+ *
+ * Copyright (c) OSGi Alliance (2004, 2006). All Rights Reserved.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.service.monitor;
+
+/**
+ * A Monitoring Job is a request for scheduled or event based notifications on
+ * update of a set of <code>StatusVariable</code>s. The job is a data
+ * structure that holds a non-empty list of <code>StatusVariable</code> names,
+ * an identification of the initiator of the job, and the sampling parameters.
+ * There are two kinds of monitoring jobs: time based and change based. Time
+ * based jobs take samples of all <code>StatusVariable</code>s with a
+ * specified frequency. The number of samples to be taken before the job
+ * finishes may be specified. Change based jobs are only interested in the
+ * changes of the monitored <code>StatusVariable</code>s. In this case, the
+ * number of changes that must take place between two notifications can be
+ * specified.
+ * <p>
+ * The job can be started on the <code>MonitorAdmin</code> interface. Running
+ * the job (querying the <code>StatusVariable</code>s, listening to changes,
+ * and sending out notifications on updates) is the task of the
+ * <code>MonitorAdmin</code> implementation.
+ * <p>
+ * Whether a monitoring job keeps track dynamically of the
+ * <code>StatusVariable</code>s it monitors is not specified. This means that
+ * if we monitor a <code>StatusVariable</code> of a <code>Monitorable</code>
+ * service which disappears and later reappears then it is implementation
+ * specific whether we still receive updates of the <code>StatusVariable</code>
+ * changes or not.
+ */
+public interface MonitoringJob {
+    /**
+     * Stops a Monitoring Job. Note that a time based job can also stop
+     * automatically if the specified number of samples have been taken.
+     */
+    public void stop();
+
+    /**
+     * Returns the identitifier of the principal who initiated the job. This is
+     * set at the time when
+     * {@link MonitorAdmin#startJob MonitorAdmin.startJob()} method is called.
+     * This string holds the ServerID if the operation was initiated from a
+     * remote manager, or an arbitrary ID of the initiator entity in the local
+     * case (used for addressing notification events).
+     * 
+     * @return the ID of the initiator, cannot be <code>null</code>
+     */
+    public String getInitiator();
+
+    /**
+     * Returns the list of <code>StatusVariable</code> names that are the
+     * targets of this measurement job. For time based jobs, the
+     * <code>MonitorAdmin</code> will iterate through this list and query all
+     * <code>StatusVariable</code>s when its timer set by the job's frequency
+     * rate expires.
+     * 
+     * @return the target list of the measurement job in
+     *         [Monitorable_ID]/[StatusVariable_ID] format, cannot be
+     *         <code>null</code>
+     */
+    public String[] getStatusVariableNames();
+
+    /**
+     * Returns the delay (in seconds) between two samples. If this call returns
+     * N (greater than 0) then the <code>MonitorAdmin</code> queries each
+     * <code>StatusVariable</code> that belongs to this job every N seconds.
+     * The value 0 means that the job is not scheduled but event based: in this
+     * case instant notification on changes is requested (at every nth change of
+     * the value, as specified by the report count parameter).
+     * 
+     * @return the delay (in seconds) between samples, or 0 for change based
+     *         jobs
+     */
+    public int getSchedule();
+
+    /**
+     * Returns the number of times <code>MonitorAdmin</code> will query the
+     * <code>StatusVariable</code>s (for time based jobs), or the number of
+     * changes of a <code>StatusVariable</code> between notifications (for
+     * change based jobs). Time based jobs with non-zero report count will take
+     * <code>getReportCount()</code>*<code>getSchedule()</code> time to
+     * finish. Time based jobs with 0 report count and change based jobs do not
+     * stop automatically, but all jobs can be stopped with the {@link #stop}
+     * method.
+     * 
+     * @return the number of measurements to be taken, or the number of changes
+     *         between notifications
+     */
+    public int getReportCount();
+
+    /**
+     * Returns whether the job was started locally or remotely.  Jobs started by
+     * the clients of this API are always local, remote jobs can only be started
+     * using the Device Management Tree.
+     * 
+     * @return <code>true</code> if the job was started from the local device,
+     *         <code>false</code> if the job was initiated from a management 
+     *         server through the device management tree
+     */
+    public boolean isLocal();
+    
+    /**
+     * Returns whether the job is running.   A job is running until it is
+     * explicitely stopped, or, in case of time based jobs with a finite report
+     * count, until the given number of measurements have been made.
+     *   
+     * @return <code>true</code> if the job is still running, <code>false</code>
+     *         if it has finished
+     */
+    public boolean isRunning();
+}



Mime
View raw message