felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1421893 [16/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/...
Date Fri, 14 Dec 2012 14:30:22 GMT
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-scr-ant-task-use.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-scr-ant-task-use.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-scr-ant-task-use.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/apache-felix-scr-ant-task-use.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,102 @@
+Title: Apache Felix SCR Ant Task Use
+Excerpt: Using the Apache Felix SCR Ant Task to generate Declarative Services and Metatype Service descriptors during an Ant driven Build.
+
+
+The SCR Ant Task is implemented in the `org.apache.felix.scr.ant` library which must be registered as an Ant Task in the build file as follows:
+
+
+    <project ...>
+    
+      <taskdef
+        resource="scrtask.properties"
+        classpath="org.apache.felix.scr.ant-1.1.4.jar" />
+    
+    </project>
+
+
+Of course the value you set in the `classpath` attribute depends on the actual location of the `org.apache.felix.scr.ant` JAR file.
+
+The SCR Ant Task is available for download from the Apache Felix [Downloads](http://felix.apache.org/site/downloads.cgi) page.
+
+*Notes*:
+* The name of the task is `scr`
+* The task requires that the source files have already been compiled
+
+The task only generates the descriptor file(s). If you want to use the Declarative Services descriptor -- by default generated in the `OSGI-INF/serviceComponents.xml` -- you must make sure to add a `Service-Components` header to your bundle manifest. Unlike Maven plugin the Ant task cannot automatically generate this header.
+
+
+## Task Attributes
+
+Like the standard `javac` Ant Task, the SCR Ant Task defines an implicit fileset which defines the source files to be scanned for Java 5 Annotations or JavaDoc Tags. In addition to the child elements available to Ant Fileset as defined for [directory-based tasks](http://ant.apache.org/manual/dirtasks.html#directorybasedtasks) the following task attributes:
+
+| Attribute | Required | Default | Description |
+|--|--|--|--|
+| scrdir | Yes | -- | The root directory of the implicitly defined fileset denoting the files to consider for annotation and/or JavaDoc tag processing. |
+| destdir | Yes | -- | The name of the directory where the descriptor files are generated into. This is also used as the directory where the compiled classes from the `srcdir` may be located. This directory is actually added as another element to the classpath as defined by `classpath` and `classpathRef`. |
+| classpath | No | -- | The class path used to load classes from to analyse for the descriptor file generation. Generally this will be the same class path as the one used to compile the sources. |
+| classpathRef | No | -- | A reference to a class path used to load classes from to analyse for the descriptor file generation. Generally this will be the same class path as the one used to compile the sources. |
+| finalName | No | `serviceComponents.xml` | The name of the descriptor file to create. This file is always located inside the `OSGI-INF` folder in the `destdir`. |
+| metaTypeName | No | `metatype.xml` | The name of the descriptor file to create. This file is always located inside the `OSGI-INF/metatype` folder in the `destdir`. |
+| generateAccessors | No | `true` | If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin. |
+| annotationTagProviders | No | -- | List of fully qualified class names providing more Annotation Tag Providers. As of version 1.4.0 of the SCR Annotations library this configuration element is optional if the SCR Annotations library comes with a proper SPI setup (see [Extending SCR Annotations]({{ refs.extending-scr-annotations.path }})) |
+| specVersion | No | Auto-Detected | The plugin will generate a descriptor for the Declarative Service version (either 1.0 or 1.1). If no value is specified, the plugin will detect the version and only use 1.1 if features from this version are used. |
+| strictMode | No | false | If set to true, a warning will be considered as an error and the build will fail with warnings generated by this task. |
+| parseJavadoc | No | true | If set to true, javadoc based annotations will be processed. |
+| processAnnotations | No | true | If set to true, SCR annotations will be processed |
+
+
+The `scr` task must be provided with the same class path as was used to compile the sources. The classes in the class path are used by the task to be able to load compiled classes (mostly for Java 5 annotation processing) and any base classes, which may be extended. The easiest way to share the class path is to define a class path property and refer to it with the `classpathref` attribute of the `scr` task.
+
+
+## Using JavaDoc Tags
+
+JavaDoc tags are supported natively by the SCR Ant Task. No further configuration and/or libraries are needed.
+
+
+## Java 5 Annotations
+
+To use Java 5 Annotations make sure the library defining the annotations is available on the class path for both the compilation in the `javac` task and for generating the descriptor in the `scr` task.
+
+No further configuration is required as the SCR Ant Task automatically recognizes SCR Annotation definitions from libraries in the class path provided the annotations are provided in a JAR library with properly setup SPI configuration as documented in [Extending SCR Annotations]({{ refs.extending-scr-annotations.path }}).
+
+
+## Example
+
+The following is very simple example build file based on the [Apache Sling JCR WebConsole](http://svn.apache.org/repos/asf/sling/trunk/bundles/jcr/webconsole) bundle:
+
+
+    <project default="scr" basedir=".">
+    
+      <taskdef resource="scrtask.properties"
+          classpath="org.apache.felix.scr.ant-1.0.0-SNAPSHOT.jar" />
+    
+      <target name="init">
+        <property name="src" value="src/main/java" />
+        <property name="classes" value="target/classes" />
+        <property name="m2Repo" value="${user.home}/.m2/repository" />
+        <path id="dependencies">
+          <fileset dir="${m2Repo}">
+            <include name="javax/jcr/jcr/1.0/jcr-1.0.jar" />
+            <include name="org/apache/sling/org.apache.sling.jcr.api/2.0.6/org.apache.sling.jcr.api-2.0.6.jar" />
+            <include name="org/apache/felix/org.apache.felix.webconsole/3.0.0/org.apache.felix.webconsole-3.0.0.jar" />
+            <include name="javax/servlet/servlet-api/2.4/servlet-api-2.4.jar" />
+            <include name="org/apache/felix/org.apache.felix.scr.annotations/1.4.0/org.apache.felix.scr.annotations-1.4.0.jar" />
+          </fileset>
+        </path>
+      </target>
+    
+      <target name="compile" depends="init">
+          <mkdir dir="${classes}" />
+          <javac srcdir="${src}" destdir="${classes}" classpathref="dependencies" />
+      </target>
+    
+      <target name="scr" depends="compile">
+        <scr srcdir="${src}" destdir="${classes}" classpathref="dependencies" />
+      </target>
+    
+      <target name="clean">
+        <delete dir="target" />
+      </target>
+    
+    </project>
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/extending-scr-annotations.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/extending-scr-annotations.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/extending-scr-annotations.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/extending-scr-annotations.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,48 @@
+Title: Extending SCR Annotations
+Excerpt: How add new Annotations extending the base Annotations
+
+
+*Note:* This page documents functionality available with the SCR Generator 1.0.0 release providing the declaration file generation mechanism for the Maven SCR Plugin 1.6.0 (and newer) and the SCR Ant Task 1.0.0 (and newer).
+
+The SCR Annotations library has been updated in version 1.4.0 to comply with the rules described here. As such the this library may be used as basis to learn more about providing pluggbale Java 5 annotations for the Maven SCR Plugin and SCR Ant Task. The source code for the SCR Annotations library is available from the Apache Felix SVN repository at [annotations](http://svn.apache.org/repos/asf/felix/trunk/scrplugin/annotations).
+
+This page outlines the required steps to implement your own extended Java 5 annotations:
+
+1. Define the Annotations
+1. Define an `AnnotationTagProvider`
+1. Register the `AnnotationsTagProvider`
+
+It is interesting to note, that the SCR Annotations 1.4.0 library providing the default and Sling Java 5 tags for the SCR Generator by itself is already implemented according to the rules outlined herein. This means, that actually the SCR Generator does not have any built-in annotations but only provides the framework to allow for the definition of Java 5 Annotations.
+
+
+## Define the Annotations
+
+To start with you will define Java 5 Annotations to suit your application needs. The [`org.apache.felix.scr.annotations.sling`](http://svn.apache.org/repos/asf/felix/trunk/scrplugin/annotations/src/main/java/org/apache/felix/scr/annotations/sling) package provides three sample annotations:
+
+* `SlingServlet` -- used to declare a `javax.servlet.Servlet` service component with the appropriate service registration properties to configure the service as an Apache Sling Servlet.
+* `SlingFilter` -- used to declare a `javax.servlet.Filter` service component with the appropriate service registration properties to configure the service as a Filter used by the Apache Sling Main Servlet.
+* `SlingFilterScope` -- helper annotation to define the `filter.scope` service registration property for Filters defined with the `SlingFilter` annotation.
+
+These annotations will be used by the application programmer to annotate his/her classes for use with Declarative Services.
+
+It is suggested to maintain the Anntoations in their own package.
+
+
+## Define an `AnnotationTagProvider`
+
+The [`AnnotationTagProvider`](http://svn.apache.org/repos/asf/felix/trunk/scrplugin/generator/src/main/java/org/apache/felix/scrplugin/tags/annotation/AnnotationTagProvider.java) interface defines the interface of a helper class which is used to convert Java 5 Annotation data into internal data structures to be then used as the basis for the generation of the descriptor files.
+
+Implementations of this interface are fed with the annotations and are expected to return a list of objects representing the actual information to be processed into the descriptor files. If a processor does not understand a particular annotations an empty list is just returned.
+
+The objects returned by the `AnnotationTagProvider` must implement the [`JavaTag`](http://svn.apache.org/repos/asf/felix/trunk/scrplugin/generator/src/main/java/org/apache/felix/scrplugin/tags/JavaTag.java) interface. To ease the implementation the [`AbstractTag`|http://svn.apache.org/repos/asf/felix/trunk/scrplugin/generator/src/main/java/org/apache/felix/scrplugin/tags/annotation/AbstractTag.java] may be used as a base class.
+
+The [`org.apache.felix.scrplugin.tags.annotation.sling`](http://svn.apache.org/repos/asf/felix/trunk/scrplugin/annotations/src/main/java/org/apache/felix/scrplugin/tags/annotations/sling) package contains the `AnnotationTagProvider` supporting Sling Annotations mentioned above as well as corresponding `JavaTag` implementations (mostly extending from `AbstractTag`).
+
+
+## Register the `AnnotationsTagProvider`
+
+To finally make the `AnnotationTagProvider` implementations available to the SCR Generator (and thus the Maven SCR Plugin and/or SCR Ant Task) the fully qualified class names of these implementations must be listed in an [`META-INF/services/org.apache.felix.scrplugin.tags.annotation.AnnotationTagProvider`](http://svn.apache.org/repos/asf/felix/trunk/scrplugin/annotations/src/main/resources/META-INF/services/org.apache.felix.scrplugin.tags.annotation.AnnotationTagProvider) file.
+
+The classes listed in this file will automatically be picked up by the SCR Generator from the library placed on the build class path and thus enable support for the respective annotations.
+
+Again, refer to the actual implementation in the SCR Annotations library referred to above.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-annotations.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,157 @@
+Title: SCR Annotations
+Excerpt: Using Java 5 Annotations to describe the component or service.
+
+
+The `maven-scr-plugin` uses the `SCR` annotations from the corresponding subproject at Apache Felix. All annotations are in the `org.apache.felix.scr.annotations` package. If you want to use the annotations in your project, you have to use a `maven-scr-plugin` version >= 1.2.0 and make sure that you add a dependency to the annotations to your `POM`:
+
+
+    <dependency>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>org.apache.felix.scr.annotations</artifactId>
+        <version>1.2.0</version>
+    </dependency>
+
+
+The following annotations are supported:
+* `[Component]({{ refs.-component.path }})`
+* `[Activate]({{ refs.-scran_componentmethod.path }})`
+* `[Deactivate]({{ refs.-scran_componentmethod.path }})`
+* `[Modified]({{ refs.-scran_componentmethod.path }})`
+* `[Service]({{ refs.-service.path }})`
+* `[Property]({{ refs.-property.path }})`
+* `[Reference]({{ refs.-reference.path }})`
+
+
+### Component
+
+The `Component` annotation is the only required annotation. If this annotation is not declared for a Java class, the class is not declared as a component.
+
+This annotation is used to declare the `<component>` element of the component declaration. See section 112.4.3, Component Element, in the OSGi Service Platform Service Compendium Specification for more information. The required `<implementation>` element is automatically generated with the fully qualified name of the class containing the `Component` annotation.
+
+Supported attributes:
+| *Name* | *Default Value* | *Required* | *SCR* | *Metatype* | *Description* |
+| name | Fully qualified name of the Java class | no | `component.name` | `OCD.id` | Defines the Component name also used as the PID for the Configuration Admin Service |
+| ds | `true` | no | --  | --  | Whether Declarative Services descriptor is generated or not. If this parameter is not set or set to `true` the Declarative Services descriptor is generated in the service descriptor file for this component. Otherwise no Declarative Services descriptor is generated for this component. |
+| specVersion | `1.0` | no | -- | -- | Defines what Declarative Services specification the component is written against. Though the Maven SCR Plugin is very good at detecting whether components are written against the original or a newer specification, there are some cases, where the plugin may fail. For these cases, the `specVersion` attribute may be set to the correct version. Currently supported values for this attribute are `1.0` and `1.1`. Since version 1.4.1 of the Maven SCR Plugin and version 1.0.1 of the SCR Annotations. |
+| componentAbstract | see description | no | --  | --  | This marks an abstract service description which is not added to the descriptor but intended for reuse through inheritance. This attribute defaults to `true` for abstract classes and `false` for concrete classes. |
+| enabled | `true` | no | `component.enabled` | --  | Whether the component is enabled when the bundle starts |
+| factory | --  | no | `component.factory` | --  | Whether the component is a factory component |
+| immediate | --  | no | `component.immediate` | --  | Whether the component is immediately activated |
+| inherit | `true` | no | --  | --  | Whether any service, property and reference declarations from base classes should be inherited by this class. |
+| metatype | `false` | no | --  | --  | Whether Metatype Service data is generated or not. If this parameter is set to `true` Metatype Service data is generated in the `metatype.xml` file for this component. Otherwise no Metatype Service data is generated for this component. |
+| label | `%<name>.name` | no | --  | `OCD.name` | This is generally used as a title for the object described by the meta type. This name may be localized by prepending a `%` sign to the name. |
+| description | `%<name>.name` | no | --  | `OCD.description` | This is generally used as a description for the object described by the meta type. This name may be localized by prepending a `%` sign to the name. |
+| createPid | `true` | no | `service.pid` | --  | Generate the `service.pid` property if non is declared. |
+| configurationFactory | `false` | no | -- | `Designate.factoryPid` | Is this a configuration factory? (since 1.4.0) |
+
+The follwing attributes are supported since version 1.4.0 of the plugin and required a Declarative Service implementation 1.1:
+| policy | `OPTIONAL` | no | component.policy | -- | The configuration policy for this component: `OPTIONAL`, `IGNORE`, or `REQUIRE` |
+
+
+#### Abstract Service Descriptions
+
+If the `Component` annotations contains the attribute `componentAbstract` with a value of true, the containing class is regarded as an abstract class. It is not added to the service descriptor and the tags are not validated. The information about this class is added to the bundle. Classes from other bundles (or the same) can extends this abstract class and do not need to specify the references of the abstract class if they set the `inherit` parameter on the `scr.component` tag to true.
+
+This allows to create abstract classes which already provide some valuable functionality without having to deal with the details like reference definitions in each and every subclass.
+
+
+
+### `Activate`, `Deactivate`, and `Modified`
+
+The Declarative Service version 1.1 allows to specify the name for the activate, deactivate and modified method (see the spec for more information). The `Activate`, `Deactivate`, and `Modified` annotation can be used to mark a method to be used for the specified purpose. However, as the DS specifies a method search algorithm, there are rare cases where the marked method is not used (if there is another method with the same name, but a different signature this might happen).
+
+
+### Service
+
+The `Service` annotation defines whether and which service interfaces are provided by the component. This is a class annotation.
+
+This tag is used to declare `<service>` and `<provide>` elements of the component declaration. See section 112.4.6, Service Elements, in the OSGi Service Platform Service Compendium Specification for more information.
+
+Supported attributes:
+| *Name* | *Default Value* | *Required* | *Descriptor* | *Description* |
+| value | All implemented interfaces | no | `provide.interface` | The name of the service interface provided by the component. This can either be the fully qualified  name or just the interface class name if the interface is either in the same package or is imported. If this property is not set `provide` elements will be generated for all interfaces generated by the class |
+| serviceFactory | `false` | no | `service.servicefactory` | Whether the component is registered as a `ServiceFactory` or not |
+Omitting the `Service` annotation will just define (and activate if required) the component but not register it as a service. Multiple `Service` annotations may be declared each with its own `value`. These annotations need to be wrapped into a `Services` anotation. The component is registered as a `ServiceFactory` if at least on `Service` annotations declares the `serviceFactory` attribute as `true`.
+
+
+
+### Property
+
+The `Property` annotation defines properties which are made available to the component through the `ComponentContext.getProperties()` method. These tags are not strictly required but may be used by components to defined initial configuration. Additionally properties may be set here to identify the component if it is registered as a service, for example the `service.description` and `service.vendor` properties.
+
+This tag may be defined in the Java Class comment of the component or in a coment to a field defining a constant with the name of the property.
+
+This tag is used to declare `<property>` elements of the component declaration. See section 112.4.5, Properties and Property Elements, in the OSGi Service Platform Service Compendium Specification for more information.
+
+Supported parameters:
+| *Name* | *Default Value* | *Required* | *SCR* | *Metatype* | *Description* |
+| name | The name of constant | yes | `property.name` | `AD.id` | The name of the property. If this tag is defined on a field with an initialization expression, the value of that expression is used as the name if the field is of type `String`. |
+| value | --  | no | `property.value` | `AD.default` | The string value of the property. This can either be a single value or an array. |
+| longValue | --  | no | `property.value` | `AD.default` | The long value of the property. This can either be a single value or an array. |
+| doubleValue | --  | no | `property.value` | `AD.default` | The double value of the property. This can either be a single value or an array. |
+| floatValue | --  | no | `property.value` | `AD.default` | The float value of the property. This can either be a single value or an array. |
+| intValue | --  | no | `property.value` | `AD.default` | The int value of the property. This can either be a single value or an array. |
+| byteValue | --  | no | `property.value` | `AD.default` | The byte value of the property. This can either be a single value or an array. |
+| charValue | --  | no | `property.value` | `AD.default` | The char value of the property. This can either be a single value or an array. |
+| boolValue | --  | no | `property.value` | `AD.default` | The boolean value of the property. This can either be a single value or an array. |
+| shortValue | --  | no | `property.value` | `AD.default` | The short value of the property. This can either be a single value or an array. |
+| label | `%<name>.name` | no | --  | `AD.name` | The label to display in a form to configure this property. This name may be localized by prepending a `%` sign to the name. |
+| description | `%<name>.description` | no | --  | `AD.description` | A descriptive text to provide the client in a form to configure this property. This name may be localized by prepending a `%` sign to the name. |
+| propertyPrivate | Depending on the name | no | --  | See description | Boolean flag defining whether a metatype descriptor entry should be generated for this property or not. By default a metatype descriptor entry, i.e. an `AD` element, is generated except for the properties `service.pid`, `service.description`, `service.id`, `service.ranking`, `service.vendor`, `service.bundlelocation` and `service.factoryPid`. If a property should not be available for display in a configuration user interface, this parameter should be set to `true`. |
+| cardinality | Depends on property value(s) | no | --  | `AD.cardinality` | Defines the cardinality of the property and its collection type. If the cardinality is negative, the property is expected to be stored in a `java.util.Vector` (primitive types such as `boolean` are boxed in the Wrapper class), if the cardinality is positive, the property is stored in an array (primitve types are unboxed, that is `Boolean` type values are stored in `boolean\[\]({{ refs..path }})`). The actual value defines the maximum number of elements in the vector or array, where `Integer.MIN*INT` describes an unbounded Vector and `Integer.MAX*INT` describes an unbounded array. If the cardinality is zero, the property is a scalar value. If the defined value of the property is set in the `value` attribute, the cardinality defaults to `0` (zero for scalar value). If the property is defined in one or more properties starting with `values`, the cardinality defaults to `Integer.MAX_INT`, that is an unb
 ounded array. |
+| options | --  | no | --  | See below | See below for a description of the `options` attribute. |
+* Generating `<properties>` elements referring to bundle entries is not currently supported.
+* Multiple property annotations can be embedded in the `Properties` annoation.
+
+
+#### Naming the Property
+
+It is important to carefully define the name of properties. By using a constant of the form
+
+
+    @Property(value="default value")
+    static final String CONSTANT_NAME = "property.name";
+
+
+and defining the `Property` annotation on this constant, the name of the property is taken from the constant value. Thus it may easily be ensured, that both the property in the descriptor files and the property used by the implementation are actually the same. In addition the value attribute can point to another constant.
+
+
+#### The `options` Parameter
+
+Some properties may only be set to a set of possible values. To support user interfaces which provide a selection list of values or a list of checkboxes the option values and labels may be defined as parameters to the `Property` annotation. All parameters in the form of name-value pairs occurring *after* the `options` attribute are used to build the list of available value options. The parameter name is used as the value while the parameter value is used as the label in the user interface. This label may be prepended with a `%` sign to localize the string.
+
+The options are written to the `metatype.xml` file as `Option` elements inside the `AD` element defining the property. The name of the parameter will be used for the `Option.value` attribute while the value of the parameter defines the `Option.label` attribute.
+
+Please note, that all parameters of the `Property` annotation occurring *after* the `options` parameter are used to build the options list. Hence no non-option value parameters should actually follow the `options` parameter.
+
+#### Multivalue Properties
+
+Generally the value of a property is scalar, that is a property has a single value such as `true`, `5` or `"This is a String"`. Such scalar values are defined with the different `value` attributes of the `Property` annotation. In the case of a scalar property value, the `cardinality` parameter value is assumed to be `0` (zero) unless of course set otherwise.
+
+There may be properties, which have a list of values, such as a list of possible URL mappings for an URL Mapper. Such multiple values are defined just by comma separate as the value of the annotation parameter.
+
+If the cardinality of the property is not explicilty set with the `cardinality` property, it defaults to `Integer.MAX_INT`, i.e. unbound array, if multiple values are defined. Otherwise the `cardinality` parameter may be set for example to a negative value to store the values in a `java.util.Vector` instead.
+
+
+
+### Reference
+
+The `Reference` annotation defines references to other services made available to the component by the Service Component Runtime.
+
+This annotation may be declared on a Class level or any Java field to which it might apply. Depending on where the annotation is declared, the parameters may have different default values.
+
+This annotation is used to declare `<reference>` elements of the component declaration. See section 112.4.7, Reference Element, in the OSGi Service Platform Service Compendium Specification for more information.
+
+Supported parameters:
+| *Name* | *Default Value* | *Required* | *Descriptor* | *Description* |
+| name | Name of the field | yes | `reference.name` | The local name of the reference. If the `Reference` annotation is declared in the class comment, this parameter is required. If the annotation is declared on a field, the default value for the `name` parameter is the name of the field |
+| interfaceReference | Type of the field | yes | `reference.interface` | The name of the service interface. This name is used by the Service Component Runtime to access the service on behalf of the component. If the `Reference` annotation is declared on a class level, this parameter is required. If the annoation is declared on a field, the default value for the `interfaceReference` parameter is the type of the field |
+| cardinality | `1..1` | no | `reference.cardinality` | The cardinality of the service reference. This must be one of value from the enumeration `ReferenceCardinality` |
+| policy | `static` | no | `reference.policy` | The dynamicity policy of the reference. If `dynamic` the service will be made available to the component as it comes and goes. If `static` the component will be deactivated and re-activated if the service comes and/or goes away. This must be one of `static` and `dynamic` |
+| target | --  | no | `reference.target` | A service target filter to select specific services to be made available. In order to be able to overwrite the value of this value by a configuration property, this parameter must be declared. If the parameter is not declared, the respective declaration attribute will not be generated |
+| bind | See description | no | `reference.bind` | The name of the method to be called when the service is to be bound to the component. The default value is the name created by appending the reference `name` to the string `bind`. The method must be declared `public` or `protected` and take single argument which is declared with the service interface type |
+| unbind | See description | no | `reference.unbind` | The name of the method to be called when the service is to be unbound from the component. The default value is the name created by appending the reference `name` to the string `unbind`. The method must be declared `public` or `protected` and take single argument which is declared with the service interface type |
+| strategy | `event` | no | `reference.strategy` | The strategy used for this reference, one of `event` or `lookup` |
+|
+*Notes*:
+* If you define a reference on a field with a strategy of `event` and there is no bind or unbind method, the plugin will create the necessary methods.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-javadoc-tags.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-javadoc-tags.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-javadoc-tags.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-maven-scr-plugin/scr-javadoc-tags.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,140 @@
+Title: SCR JavaDoc Tags
+Excerpt: Using JavaDoc Tags to describe the component or service.
+
+
+The `scr` goal of the `maven-scr-plugin` looks for the following JavaDoc tags when building component descriptors:
+* `[scr.component]({{ refs.-scr-component.path }})`
+* `[scr.property]({{ refs.-scr-property.path }})}}
+* `[scr.service]({{ refs.-scr-service.path }})`
+* `[scr.reference]({{ refs.-scr-reference.path }})`
+
+
+
+### scr.component
+
+The `scr.component` tag is the only required tag. If this tag is not declared in the Java class comment, the class is not declared as a component.
+
+This tag is used to declare the `<component>` element of the component declaration. See section 112.4.3, Component Element, in the OSGi Service Platform Service Compendium Specification for more information. The required `<implementation>` element is automatically generated with the fully qualified name of the class containing the `scr.component` tag.
+
+Supported parameters:
+| *Name* | *Default Value* | *Required* | *SCR* | *Metatype* | *Description* |
+| name | Fully qualified name of the Java class | no | `component.name` | `OCD.id` | Defines the Component name also used as the PID for the Configuration Admin Service |
+| ds | `true` | no | --  | --  | Whether Declarative Services descriptor is generated or not. If this parameter is not set or set to `true` the Declarative Services descriptor is generated in the service descriptor file for this component. Otherwise no Declarative Services descriptor is generated for this component. |
+| abstract | see description | no | --  | --  | This marks an abstract service description which is not added to the descriptor but intended for reuse through inheritance. This attribute defaults to `true` for abstract classes and `false` for concrete classes. |
+| enabled | `true` | no | `component.enabled` | --  | Whether the component is enabled when the bundle starts |
+| factory | --  | no | `component.factory` | --  | Whether the component is a factory component |
+| immediate | --  | no | `component.immediate` | --  | Whether the component is immediately activated |
+| inherit | `true` | no | --  | --  | Whether any service, property and reference declarations from base classes should be inherited by this class. |
+| metatype | `true` | no | --  | --  | Whether Metatype Service data is generated or not. If this parameter is not set or set to `true` Metatype Service data is generated in the `metatype.xml` file for this component. Otherwise no Metatype Service data is generated for this component. |
+| label | `%<name>.name` | no | --  | `OCD.name` | This is generally used as a title for the object described by the meta type. This name may be localized by prepending a `%` sign to the name. |
+| description | `%<name>.name` | no | --  | `OCD.description` | This is generally used as a description for the object described by the meta type. This name may be localized by prepending a `%` sign to the name. |
+| create-pid | `true` | no | `service.pid` | --  | Generate the `service.pid` property if non is declared. |
+| configurationFactory | `false` | no | -- | `Designate.factoryPid` | Is this a configuration factory? (since 1.4.0) |
+
+The follwing attributes are supported since version 1.4.0 of the plugin and required a Declarative Service implementation 1.1:
+| policy | `OPTIONAL` | no | component.policy | -- | The configuration policy for this component: `optional`, `ignore`, or `require` (use lower case words) |
+| activate | `activate` | no | component.activate | -- | The name of the component activation method. |
+| deactivate | `deactivate` | no | component.deactivate | -- | The name of the component deactivation method. |
+| modified | -- | no | component.modified | -- | The name of the component modified method. |
+
+#### Abstract Service Descriptions
+
+If the `scr.component` tag contains the parameter `abstract` with a value of true, the containing class is regarded as an abstract class. It is not added to the service descriptor and the tags are not validated. The information about this class is added to the bundle. Classes from other bundles (or the same) can extends this abstract class and do not need to specify the references of the abstract class if they set the `inherit` parameter on the `scr.component` tag to true.
+
+This allows to create abstract classes which already provide some valuable functionality without having to deal with the details like reference definitions in each and every subclass.
+
+
+### scr.property
+
+The `scr.property` tag defines properties which are made available to the component through the `ComponentContext.getProperties()` method. These tags are not strictly required but may be used by components to defined initial configuration. Additionally properties may be set here to identify the component if it is registered as a service, for example the `service.description` and `service.vendor` properties.
+
+This tag may be defined in the Java Class comment of the component or in a coment to a field defining a constant with the name of the property.
+
+This tag is used to declare `<property>` elements of the component declaration. See section 112.4.5, Properties and Property Elements, in the OSGi Service Platform Service Compendium Specification for more information.
+
+Supported parameters:
+| *Name* | *Default Value* | *Required* | *SCR* | *Metatype* | *Description* |
+| name | The name of constant | yes | `property.name` | `AD.id` | The name of the property. If this tag is defined on a field with an initialization expression, the value of that expression is used as the name if the field is of type `String`. |
+| value | --  | no | `property.value` | `AD.default` | The value of the property. If the property type is not `String`, parsing of the value is done using the `valueOf(String)` method of the class defined by the property type |
+| type | `String` | no | `property.type` | `AD.type` | The type of the property value. This must be one of `String`, `Long`, `Double`, `Float`, `Integer`, `Byte`, `Char`, `Boolean` and `Short`. |
+| label | `%<name>.name` | no | --  | `AD.name` | The label to display in a form to configure this property. This name may be localized by prepending a `%` sign to the name. |
+| description | `%<name>.description` | no | --  | `AD.description` | A descriptive text to provide the client in a form to configure this property. This name may be localized by prepending a `%` sign to the name. |
+| private | Depending on the name | no | --  | See description | Boolean flag defining whether a metatype descriptor entry should be generated for this property or not. By default a metatype descriptor entry, i.e. an `AD` element, is generated except for the properties `service.pid`, `service.description`, `service.id`, `service.ranking`, `service.vendor`, `service.bundlelocation` and `service.factoryPid`. If a property should not be available for display in a configuration user interface, this parameter should be set to `true`. |
+| cardinality | Depends on property value(s) | no | --  | `AD.cardinality` | Defines the cardinality of the property and its collection type. If the cardinality is negative, the property is expected to be stored in a `java.util.Vector` (primitive types such as `boolean` are boxed in the Wrapper class), if the cardinality is positive, the property is stored in an array (primitve types are unboxed, that is `Boolean` type values are stored in `boolean\[\]({{ refs..path }})`). The actual value defines the maximum number of elements in the vector or array, where `Integer.MIN*INT` describes an unbounded Vector and `Integer.MAX*INT` describes an unbounded array. If the cardinality is zero, the property is a scalar value. If the defined value of the property is set in the `value` attribute, the cardinality defaults to `0` (zero for scalar value). If the property is defined in one or more properties starting with `values`, the cardinality defaults to `Integer.MAX_INT`, that is an unb
 ounded array. |
+| options | --  | no | --  | See below | See below for a description of the `options` parameter. |
+| values\* | --  | no | --  | See below | See below for a description of parameters starting with `values`. |
+| valueRef | --  | no | --  | `AD.default` | A constant containing the value for this property. The constant can either be declared in the same class as this property or in any class that is imported. The type of the property is derived from the constant. |
+| valueRefs | --  | no | --  | See below | Same as the `values` attribute with the difference that it acts like the `valueRef` attribute and the value points to a constants defining the multi value for the property. |
+*Notes*:
+* Generating `<properties>` elements referring to bundle entries is not currently supported.
+
+
+#### Naming the property
+
+It is important to carefully define the name of properties. By using a constant of the form
+
+
+    /** @scr.property value="default value" */
+    static final String CONSTANT_NAME = "property.name";
+
+
+and defining the `scr.property` tag on this constant, the name of the property is taken from the constant value. Thus it may easily be ensured, that both the property in the descriptor files and the property used by the implementation are actually the same.
+
+
+#### The `options` parameter
+
+Some properties may only be set to a set of possible values. To support user interfaces which provide a selection list of values or a list of checkboxes the option values and labels may be defined as parameters to the `scr.property` tag. All parameters in the form of name-value pairs occurring *after* the `options` parameter are used to build the list of available value options. The parameter name is used as the value while the parameter value is used as the label in the user interface. This label may be prepended with a `%` sign to localize the string.
+
+The options are written to the `metatype.xml` file as `Option` elements inside the `AD` element defining the property. The name of the parameter will be used for the `Option.value` attribute while the value of the parameter defines the `Option.label` attribute.
+
+Please note, that all parameters of the `scr.property` tag occurring *after* the `options` parameter are used to build the options list. Hence no non-option value parameters should actually follow the `options` parameter.
+
+
+#### Multivalue properties
+
+Generally the value of a property is scalar, that is a property has a single value such as `true`, `5` or `"This is a String"`. Such scalar values are defined with the `value` parameter of the `scr.property` tag. In the case of a scalar property value, the `cardinality` parameter value is assumed to be `0` (zero) unless of course set otherwise.
+
+There may be properties, which have a list of values, such as a list of possible URL mappings for an URL Mapper. Such multiple values are defined in one more parameters whose name starts with `values`. Each parameter must of course have a unique name which is not in any except to differentiate the parameters.
+
+If the cardinality of the property is not explicilty set with the `cardinality` property, it defaults to `Integer.MAX_INT`, i.e. unbound array, if multiple values with a series of `values` parameters are defined. Otherwise the `cardinality` parameter may be set for example to a negative value to store the values in a `java.util.Vector` instead.
+
+
+
+### scr.service
+
+The `scr.service` tag defines whether and which service interfaces are provided by the component.
+
+This tag is expected in the Java Class comment of the component.
+
+This tag is used to declare `<service>` and `<provide>` elements of the component declaration. See section 112.4.6, Service Elements, in the OSGi Service Platform Service Compendium Specification for more information.
+
+Supported parameters:
+| *Name* | *Default Value* | *Required* | *Descriptor* | *Description* |
+| interface | All implemented interfaces | no | `provide.interface` | The name of the service interface provided by the component. This can either be the fully qualified  name or just the interface class name if the interface is either in the same package or is imported. If this property is not set `provide` elements will be generated for all interfaces generated by the class |
+| servicefactory | `false` | no | `service.servicefactory` | Whether the component is registered as a `ServiceFactory` or not |
+Omitting the `scr.service` tag will just define (and activate if required) the component but not register it as a service. Multiple `scr.service` tags may be declared each with its own `interface`. The component is registered as a `ServiceFactory` if at least on `scr.service` tag declares the `servicefactory` parameter as `true`.
+
+
+
+### scr.reference
+
+The `scr.reference` tag defines references to other services made available to the component by the Service Component Runtime.
+
+This tag may be declared in the java Class comment or any Java Field to which it might apply. Depending on where the tag is declared, the parameters may have different default values.
+
+This tag is used to declare `<reference>` elements of the component declaration. See section 112.4.7, Reference Element, in the OSGi Service Platform Service Compendium Specification for more information.
+
+Supported parameters:
+| *Name* | *Default Value* | *Required* | *Descriptor* | *Description* |
+| name | Name of the field | yes | `reference.name` | The local name of the reference. If the `scr.reference` tag is declared in the class comment, this parameter is required. If the tag is declared in the field comment, the default value for the `name` parameter is the name of the field |
+| interface | Type of the field | yes | `reference.interface` | The name of the service interface. This name is used by the Service Component Runtime to access the service on behalf of the component. If the `scr.reference` tag is declared in the class comment, this parameter is required. If the tag is declared in the field comment, the default value for the `interface` parameter is the type of the field |
+| cardinality | `1..1` | no | `reference.cardinality` | The cardinality of the service reference. This must be one of `0..1`, `1..1`, `0..n`, and `1..n` |
+| policy | `static` | no | `reference.policy` | The dynamicity policy of the reference. If `dynamic` the service will be made available to the component as it comes and goes. If `static` the component will be deactivated and re-activated if the service comes and/or goes away. This must be one of `static` and `dynamic` |
+| target | --  | no | `reference.target` | A service target filter to select specific services to be made available. In order to be able to overwrite the value of this value by a configuration property, this parameter must be declared. If the parameter is not declared, the respective declaration attribute will not be generated |
+| bind | See description | no | `reference.bind` | The name of the method to be called when the service is to be bound to the component. The default value is the name created by appending the reference `name` to the string `bind`. The method must be declared `public` or `protected` and take single argument which is declared with the service interface type |
+| unbind | See description | no | `reference.unbind` | The name of the method to be called when the service is to be unbound from the component. The default value is the name created by appending the reference `name` to the string `unbind`. The method must be declared `public` or `protected` and take single argument which is declared with the service interface type |
+| strategy | `event` | no | `reference.strategy` | The strategy used for this reference, one of `event` or `lookup` |
+|
+
+*Notes*:
+* If you define a reference on a field with the strategy `event` and there is no bind or unbind method, the plugin will create the necessary methods.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-metatype-service.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-metatype-service.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-metatype-service.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-metatype-service.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,126 @@
+Title: Apache Felix Metatype Service
+
+# Apache Felix Metatype Service
+
+The OSGi Metatype specification provides a unified way to describe metadata about services and a Java interface to retrieve and manipulate such information. This information can optionally be localized, thus allowing the developer to provide human-readable metadata descriptions in multiple languages. The specification defines a rich dynamic typing system to describe service attributes in a precise way, which makes it possible to dynamically create user interfaces to configure services.
+
+The simplest way to specify service metatype information is to add one or more XML files in the `OSGI-INF/metatype` folder.
+For example, the `OSGI-INF/metatype/metatype.xml` file included in the [Apache Felix File Install]({{ refs.apache-felix-file-install.path }}) subproject is as follows:
+
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.0.0">
+    
+      <OCD description="FileInstaller" name="org.apache.felix.fileinstall" id="org.apache.felix.fileinstall">
+           
+        <AD name="Poll directory"  id="felix.fileinstall.dir" required="true" type="String" default="load"/>   
+        <AD name="Poll interval"  id="felix.fileinstall.poll" required="false" type="String" default="5000"/>
+        <AD name="Debug"  id="felix.fileinstall.debug" required="false" type="String" default="-1"/>
+        <AD name="Start new bundles?"  id="felix.fileinstall.bundles.new.start" required="false" type="String" default="true"/>
+        
+      </OCD>
+      
+        <Designate pid="org.apache.felix.fileinstall">
+            <Object ocdref="org.apache.felix.fileinstall"/>
+        </Designate>
+      
+    </metatype:MetaData>
+
+
+The main elements of this simple example are:
+
+* *OCD*, Object Class Definition; contains the information about a set of attributes.
+* *AD*, Attribute Definition; describes an attribute (name, description, unique id, type, cardinality, default value, ...).
+* *Designate*, defines the association between an Object Class Definition and a pid; the pid can be a reference to a factory or a singleton configuration object.
+
+The following types are supported by the specification:
+
+* String
+* Long
+* Double
+* Float
+* Integer
+* Byte
+* Char
+* Boolean
+* Short
+
+## Localization
+
+As mentioned before, it is possible to localize metatype information. A good example is the [Apache Felix Web Console]({{ refs.apache-felix-web-console.path }}) subproject, which includes the following metatype information: 
+
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    
+    <metatype:MetaData xmlns:metatype="http://www.osgi.org/xmlns/metatype/v1.0.0" localization="OSGI-INF/metatype/metatype">
+    
+        <OCD id="org.apache.felix.webconsole.internal.servlet.OsgiManager" name="%manager.name" description="%manager.description">
+            <AD id="manager.root" type="String" default="/system/console" name="%manager.root.name" description="%manager.root.description"/>
+            <AD id="default.render" type="String" default="bundles" name="%default.render.name" description="%default.render.description"/>
+            <AD id="realm" type="String" default="OSGi Management Console" name="%realm.name" description="%realm.description"/>
+            <AD id="username" type="String" default="admin" name="%username.name" description="%username.description"/>
+            <AD id="password" type="String" default="admin" name="%password.name" description="%password.description"/>
+        </OCD>
+        
+        <Designate pid="org.apache.felix.webconsole.internal.servlet.OsgiManager">
+            <Object ocdref="org.apache.felix.webconsole.internal.servlet.OsgiManager"/>
+        </Designate>
+        
+    </metatype:MetaData>
+
+
+The key elements to write a localized metatype definition are
+
+* The *localization* attribute, that points to the property file that localize this XML.
+* The *%* notation that specifies a localizable string name.
+* One or more property files defining localized strings.
+
+The following example shows the localization property file of the Web Console:
+
+
+    manager.name = Apache Felix OSGi Management Console
+    manager.description = Configuration of the Apache Felix OSGi Management Console.
+    
+    manager.root.name = Root URI
+    manager.root.description = The root path to the OSGi Management Console.
+    
+    realm.name = Realm
+    realm.description = The name of the HTTP Authentication Realm.
+    
+    username.name = User Name
+    username.description = The name of the user allowed to access the OSGi \
+     Management Console. To disable authentication clear this value.
+    
+    password.name = Password
+    password.description = The password for the user allowed to access the OSGi \
+     Management Console.
+     
+    default.render.name = Default Page
+    default.render.description = The name of the default configuration page \
+     when invoking the OSGi Management console.
+
+
+## Metatype Service API
+
+Before using the Metatype Service API, it's worth noting that this specification is not part of the OSGi core specification, so it's not included in the standard Felix distribution. It is therefore necessary to download and install the additional Metatype bundle.
+
+Accessing the Metatype service is as simple as performing a lookup in the service registry:
+
+
+      ServiceReference metatypeRef = bundleContext.getServiceReference(MetaTypeService.class.getName());
+      MetaTypeService service = (MetaTypeService) bundleContext.getService(metatypeRef);
+      
+      MetaTypeInformation information = service.getMetaTypeInformation(myBundle);
+
+
+After retrieving the `MetaTypeInformation` object for the required bundle, we have access to all the information contained in the metatype XML definition. In particular, it is possible to access the ObjectClassDefinition (optionally specifying a locale):
+
+
+      ObjectClassDefinition ocd = information.getObjectClassDefinition(pid, locale);
+
+
+With the `ObjectClassDefinition`, it is possible to retrieve all the attribute definitions:
+
+
+      AttributeDefinition[] attributes = ocd.getAttributeDefinitions(ObjectClassDefinition.ALL); 
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-bundle-repository.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-bundle-repository.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-bundle-repository.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-bundle-repository.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,313 @@
+Title: Apache Felix OSGi Bundle Repository
+
+# Apache Felix OSGi Bundle Repository (OBR)
+
+[TOC]
+
+
+
+## Motivation
+
+The goal of the Apache Felix OSGi Bundle Repository (OBR) is two-fold:
+
+1. To simplify deploying and using available bundles with Felix.
+1. To encourage independent bundle development so that communities of interest can grow.
+
+OBR achieves the first goal by providing a service that can automatically install a bundle, with its deployment dependencies, from a bundle repository. This makes it easier for people to experiment with existing bundles. The second goal is achieved by raising the visibility of the available bundles and providing access to both the executable bundle and its source code. Hopefully, by making OBR and the bundles themselves more visible, community members will be encouraged to provide or improve service implementations.
+
+Note: OBR provides access to the Felix' default bundle repository, but you can also use it to deploy your own bundles by creating a bundle repository meta-data file for your local bundles; see the `obr list-url`, `obr add-url`, and `obr remove-url` commands for more details.
+
+
+
+## Overview
+
+For the most part, OBR is quite simple. An OBR "repository server" is not necessary, since all functionality may reside on the client side. OBR is able to provide its functionality by reading an XML-based meta-data file that describes the bundles available to it. The meta-data file essentially contains an XML encoding of the bundles' manifest information. From the meta-data, OBR is able to construct dependency information for deploying (i.e., installing and updating) bundles.
+
+OBR defines the following entities:
+
+* **Repository Admin** - a service to access a federation of repositories.
+* **Repository** - provides access to a set of resources.
+* **Resource** - a description of an artifact to be installed on a device.
+* **Capability** - a named set of properties.
+* **Requirement** - an assertion on a capability.
+* **Resolver** - an object to resolve resource dependencies and to deploy them.
+* **Repository file** - XML file containing resource meta-data.
+
+The following diagram illustrates the relationships among these entities:
+
+!obr-entities.png!
+
+The client has access to a federated set of repositories via the Repository Admin service; such as depicted in this view:
+
+!obr-high-level.png!
+
+
+
+## OBR Repository File
+
+The OBR repository file is an XML-based representation of bundle meta-data. The goal is provide a generic model for describing dependencies among resources; as such, the term **resource** is used instead of **bundle** in the OBR repository syntax; a detailed description of the OBR meta-data format is available in the [OSGi RFC 112](http://www2.osgi.org/download/rfc-0112_BundleRepository.pdf) document; this document is not completely in sync with the implementation, but the concepts are still correct. The following XML snippet depicts the overall structure of a repository file:
+
+
+    <repository presentationname="..." symbolicname="..." ... >
+        <resource>
+            <description>...</description>
+            <size>...</size>
+            <documentation>...</documentation>
+            <source>...</source>
+            <category id="..."/>
+            <capability>...</capability>
+            ...
+            <requirement>...</requirement>
+            ...
+        </resource>
+        ...
+    </repository>
+
+
+The above repository defines a set of available resources, each described by a set of meta-data. Some resource meta-data is purely intended for human consumption; the most important aspects relate to the generic capability/requirement model.
+
+A resource can provide any number of capabilities. A capability is a typed set of properties. For example, the following is an exported package capability:
+
+
+    <capability name='package'>
+        <p n='package' v='org.foo.bar'/>
+        <p n='version' t='version' v='1.0.0'/>
+    </capability>
+
+
+This capability is of type 'package' and exports 'org.foo.bar' at version '1.0.0'. Conversely, a requirement is a typed LDAP query over a set of capability properties. For example, the following is an imported package requirement:
+
+
+    <require name='package' extend='false'
+        multiple='false' optional='false'
+        filter='(&amp;(package=org.foo.bar)(version&gt;=1.0.0))'>
+        Import package org.foo.bar
+    </require>
+
+
+This requirement is of type 'package' and imports 'org.foo.bar' at versions greater than '1.0.0'. Although this syntax looks rather complicated with the '\&amp;' and '\&gt;=' syntax, it is simply the standard OSGi LDAP query syntax in XML form (additionally, Peter Kriens has created a tool called `bindex` to generate this meta-data from a bundle's manifest).
+
+With this generic dependency model, OBR is able to provide mappings for the various OSGi bundle dependencies; e.g., import/export package, provide/require bundle, host/fragment, import/export service, execution environment, and native code. In addition, it is possible for bundles to introduce arbitrary dependencies for custom purposes.
+
+Two other important pieces of meta-data are `Bundle-SymbolicName` and `Bundle-Version`; these are standard OSGi bundle manifest attributes that OBR uses to uniquely identify a bundle. For example, if you want to use OBR to update a locally installed bundle, OBR gets its symbolic name and version and searches the repository metadata for a matching symbolic name. If the matching symbolic name is found, then OBR checks if there is a newer version than the local copy using the bundle version number. Thus, the symbolic name plus bundle version forms a unique key to match locally installed bundles to remotely available bundles.
+
+
+
+## OBR Service API
+
+Typically, OBR service clients only need to interact with the Repository Admin service, which provides the mechanisms necessary to discover available resources. The Repository Admin interface is defined as follows:
+
+
+    public interface RepositoryAdmin
+    {
+        public Resource[] discoverResources(String filterExpr);
+        public Resolver resolver();
+        public Repository addRepository(URL repository)?
+            throws Exception;
+        public boolean removeRepository(URL repository);
+        public Repository[] listRepositories();
+        public Resource getResource(String respositoryId);
+    }
+
+
+In order to resolve and deploy available resources, the Repository Admin provides Resolver instances, which are defined as follows:
+
+
+    public interface Resolver
+    {
+        public void add(Resource resource);
+        public Requirement[] getUnsatisfiedRequirements();
+        public Resource[] getOptionalResources();
+        public Requirement[] getReason(Resource resource);
+        public Resource[] getResources(Requirement requirement);
+        public Resource[] getRequiredResources();
+        public Resource[] getAddedResources();
+        public boolean resolve();
+        public void deploy(boolean start);
+    }
+
+
+When desired resources are discovered via the query mechanisms of the Repository Admin, they are added to a Resolver instance which will can be used to resolve all transitive dependencies and to reflect on any resolution result. The following code snippet depicts a typical usage scenario:
+
+
+    RepositoryAdmin repoAdmin = ... // Get repo admin service
+    Resolver resolver = repoAdmin.resolver();
+    Resource resource = repoAdmin.discoverResources(filterStr);
+    resolver.add(resource);
+    if (resolver.resolve())
+    {
+        resolver.deploy(true);
+    }
+    else
+    {
+        Requirement[] reqs = resolver.getUnsatisfiedRequirements();
+        for (int i = 0; i < reqs.length; i++)
+        {
+            System.out.println("Unable to resolve: " + reqs[i]);
+        }
+    }
+
+
+This code gets the Repository Admin service and then gets a Resolver instance from it. It then discovers an available resource and adds it to the resolver. Then it tries to resolve the resources dependencies. If successful it deploys the resource to the local framework instance; if not successful it prints the unsatisfied requirements.
+
+OBR's deployment algorithm appears simple at first glance, but it is actually somewhat complex due to the nature of deploying independently developed bundles. For example, in an ideal world, if an update for a bundle is made available, then updates for all of the bundles satisfying its dependencies are also made available. Unfortunately, this may not be the case, thus the deployment algorithm might have to install new bundles during an update to satisfy either new dependencies or updated dependencies that can no longer be satisfied by existing local bundles. In response to this type of scenario, the OBR deployment algorithm tries to favor updating existing bundles, if possible, as opposed to installing new bundles to satisfy dependencies.
+
+In the general case, OBR user's will not use the OBR API directly, but will use its functionality indirectly from another tool or user interface. For example, interactive access to OBR is available via a command for Felix' [shell service]({{ refs.apache-felix-shell.path }}). The OBR shell command is discussed in the next section.
+
+
+
+## OBR Shell Command
+
+Besides providing a service API, OBR implements a Felix shell command for accessing its functionality. For the end user, the OBR shell command is accessed using the text-based or GUI-based user interfaces for Felix' shell service. This section describes the syntax for the OBR shell command.
+
+
+
+### obr help
+
+Syntax:
+
+    obr help [add-url | remove-url | list-url | list | info | deploy | start | source | javadoc]
+
+This command is used to display additional information about the other OBR commands.
+
+
+
+### obr list-url
+
+Syntax:
+
+    obr list-url
+
+This command gets the URLs to the repository files used by the Repository Admin.
+
+
+
+### obr add-url
+
+Syntax:
+
+    obr add-url [<repository-file-url> ...]
+
+This command adds a repository file to the set of repository files for which the Repository Admin service provides access. The repository file is represented as a URL. If the repository file URL is already in the Repository Admin's set of repository files, the request is treated like a reload operation.
+
+
+
+### obr remove-url
+
+Syntax:
+
+    obr remove-url [<repository-file-url> ...]
+
+This command removes a repository file to the set of repository files for which the Repository Admin service provides access. The repository file is represented as a URL.
+
+
+
+### obr list
+
+Syntax:
+
+    obr list [<string> ...]
+
+This command lists bundles available in the bundle repository. If no arguments are specified, then all available bundles are listed, otherwise any arguments are concatenated with spaces and used as a substring filter on the bundle names.
+
+
+
+### obr info
+
+Syntax:
+
+    obr info <bundle-name>[;<version>] ...
+
+This command displays the meta-data for the specified bundles. If a bundle's name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:
+
+    obr info "Bundle Repository";1.0.0
+
+The above example retrieves the meta-data for version "1.0.0" of the bundle named "Bundle Repository".
+
+
+
+### obr deploy
+
+Syntax:
+
+    obr deploy <bundle-name>[;<version>] ... | <bundle-id> ...
+
+This command tries to install or update the specified bundles and all of their dependencies by default. You can specify either the bundle name or the bundle identifier. If a bundle's name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:
+
+    obr deploy "Bundle Repository";1.0.0
+
+For the above example, if version "1.0.0" of "Bundle Repository" is already installed locally, then the command will attempt to update it and all of its dependencies; otherwise, the command will install it and all of its dependencies.
+
+
+
+### obr start
+
+Syntax:
+
+    obr start [-nodeps] <bundle-name>[;<version>] ...
+
+This command installs and starts the specified bundles and all of their dependencies by default; use the "-nodeps" switch to ignore dependencies. If a bundle's name contains spaces, then it must be surrounded by quotes. If a specified bundle is already installed, then this command has no effect. It is also possible to specify a precise version if more than one version exists, such as:
+
+    obr start "Bundle Repository";1.0.0
+
+The above example installs and starts the "1.0.0" version of the bundle named "Bundle Repository" and its dependencies.
+
+
+
+### obr source
+
+Syntax:
+
+    obr source [-x] <local-dir> <bundle-name>[;<version>] ...
+
+This command retrieves the source archives of the specified bundles and saves them to the specified local directory; use the "-x" switch to automatically extract the source archives. If a bundle name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:
+
+    obr source /home/rickhall/tmp "Bundle Repository";1.0.0
+
+The above example retrieves the source archive of version "1.0.0" of the bundle named "Bundle Repository" and saves it to the specified local directory.
+
+### obr javadoc
+
+Syntax:
+
+    obr javadoc [-x] <local-dir> <bundle-name>[;<version>] ...
+
+This command retrieves the javadoc archives of the specified bundles and saves them to the specified local directory; use the "-x" switch to automatically extract the javadoc archives. If a bundle name contains spaces, then it must be surrounded by quotes. It is also possible to specify a precise version if more than one version exists, such as:
+
+    obr javadoc /home/rickhall/tmp "Bundle Repository";1.0.0
+
+The above example retrieves the javadoc archive of version "1.0.0" of the bundle named "Bundle Repository" and saves it to the specified local directory.
+
+
+
+## Using OBR with a Proxy
+
+If you use a proxy for Web access, then OBR will not work for you in its default configuration; certain system properties must be set to enable OBR to work with a proxy. These properties are:
+
+* http.proxyHost - the name of the proxy host.
+* http.proxyPort - the port of the proxy host.
+* http.proxyAuth - the user name and password to use when connecting to the proxy; this string should be the user name and password separated by a colon (e.g., rickhall:mypassword).
+
+These system properties can be set directly on the command line when starting the JVM using the standard "-D<prop>=<value>" syntax or you can put them in the lib/system.properties file of your Felix installation; see documentation on configuring Felix for more information.
+
+
+
+## Bundle Source Packaging
+
+Coming soon...
+
+
+
+## Note on OSGi R3 Bundles
+
+In contrast to OSGi R4 the previous specifications, most notably R3, allowed bundles without the `Bundle-SymbolicName` header. The Felix OSGi Bundle Repository implementation heavily relies on the symbolic name being defined in bundles. As a consequence bundles without a symbolic name are not fully supported by the Bundle Repository:
+
+   * Bundles installed in the framework are used by the Bundle Repository implementation to resolve dependencies regardless of whether they have a `Bundle-SymbolicName` header or not. Resolution of dependencies against the installed bundles takes place based on the `Export-Package` headers.
+   * Bundles installed in the framework without a `Bundle-SymbolicName` header cannot be updated by the Bundle Repository implementation because updates from the bundle repository cannot be correlated to such "anonymous" bundles.
+
+
+
+
+## Feedback
+
+Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-core.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-core.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-core.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-osgi-core.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,5 @@
+Title: Apache Felix OSGi Core
+
+# Apache Felix OSGi Core
+
+The Apache Felix OSGi Core sub-project simply repackages the standard OSGi core API packages provided by the OSGi Alliance into a Maven module. Nearly all OSGi-related projects will have a dependency on this module if using Maven or will require this module's JAR file in its class path in order to compile against the OSGi core APIs. The Felix framework has a compile-time dependency on the OSGi core module, but at packaging time it embeds the specific set of required packages so there is no longer a dependency on the module at execution time.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-preferences-service.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-preferences-service.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-preferences-service.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-preferences-service.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,88 @@
+Title: Apache Felix Preferences Service
+
+# Apache Felix Preferences Service
+
+The OSGi service compendium specification defines a general purpose service to store data persistently, so that they can survive the restart of a bundle or of the whole OSGi container. This service is not intended to be a full-featured persistence layer for OSGi bundles, rather a simple tool to store informations that can be used in various stages of the bundle lifecycle.
+
+The service supports the storage of scalar values (boolan, double, float, int, long and strings) and byte arrays, arranged in a hierarchical model. While there is no limitations on the size of data objects stored, the specification clearly states that the Preferences Service is intended to store only small objects.
+
+The entry point to the Preferences Service API is the *PreferencesService* interface. It provides access to different roots of Preferences trees:
+* a *system root* 
+* any number of *user roots*
+The *user root* for a specific user is automatically created the first time it is requested.
+
+User roots and system root are bundle specific, and cannot be accessed by other bundles. 
+
+## Accessing the Preferences Service
+
+If the OSGi platform provides a Preferences Service, getting a reference to it is as simple as doing a normal OSGi service lookup:
+
+
+    public class Activator implements BundleActivator
+    {
+    	public void start(BundleContext context) throws Exception 
+    	{	
+    		ServiceReference ref = context.getServiceReference(PreferencesService.class.getName());
+    		if (ref != null)
+    		{
+    			PreferencesService service = (PreferencesService) context.getService(ref);
+    	
+    			//...
+    		}
+    	}
+    
+    	//..
+
+
+To access the *system root*
+
+
+    		Preferences systemRoot = service.getSystemPreferences();
+
+
+To access a *user root*
+
+
+    		Preferences mickeyRoot = service.getUserPreferences("mickey");
+
+
+## Store and retrieve value in Preferences 
+
+The *Preferences* interface offers some simple methods to store key/value pairs:
+
+    public void put(String key, String value);
+    
+    public void putInt(String key, int value);
+                       
+    public void putLong(String key, long value);
+                        
+    public void putBoolean(String key, boolean value);
+                           
+    public void putFloat(String key, float value);
+                         
+    public void putDouble(String key, double value);
+                          
+    public void putByteArray(String key, byte[] value);
+
+
+For each of these methods, a correspondent *get* method exists. Get methods always accept two arguments: the first to specify the key of the property to retrieve, the second a default value in case of not-existent property (or in case of errors). For instance:
+
+
+    public float getFloat(String key, float def)
+
+
+As mentioned before, data can be stored in a hierarchical way. The following example shows how to create nodes under the system root to store data:
+
+
+    Preferences colorPreferences = service.getSystemPreferences().node("color");
+    colorPreferences.setString("background", "#eeeeee");
+    colorPreferences.setString("font", "#000000");
+
+
+The Preferences interface offers different method to navigate the preference tree, like `childrenNames(), parent() and node(String name)`. Check the [Preferences interface Javadoc](http://www.osgi.org/javadoc/r4v41/org/osgi/service/prefs/Preferences.html) for a complete list.
+
+## flush() and sync()
+
+Two additional methods of the *Preferences* interface can be useful.
+* *flush()* forces any change of the Preferences object to be saved in the persistent storage
+* *sync()* reload the content of the Preferences object from the persistent storage; before reloading, all the contents are saved
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-remote-shell.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-remote-shell.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-remote-shell.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-remote-shell.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,34 @@
+Title: Apache Felix Remote Shell
+
+# Apache Felix Remote Shell
+
+The Apache Felix Remote Shell provided by the `org.apache.felix.shell.remote` bundle offers remote access to [Apache Felix Shell]({{ refs.apache-felix-shell.path }}) and [Apache Felix Gogo] using telnet clients. The remote shell provides simple telnet access with no bells and whistles -- it just works.
+
+To use remote shell with the Felix shell, you have to install the `org.apache.felix.shell` bundle in addition to the `org.apache.felix.shell.remote` bundle. To use it with Gogo, you have to install the `org.apache.felix.gogo.runtime` and `org.apache.felix.gogo.shell` bundles in addition to the `org.apache.felix.shell.remote` bundle. Once you have the shell bundles installed with the remote shell bundle, start them all to enable remote shell access.
+
+<div class="info" markdown="1">
+**Default shell**
+If you have both the Felix shell and Gogo installed and active, then the default is to connect to Gogo when you telnet into the remote shell. If you wish to telnet into the Felix shell, you should stop the Gogo runtime bundle.
+</div>
+
+## Configuration
+
+The Apache Felix Remote Shell bundle currently is configured using framework properties obtained from the bundle's context. The following properties are supported:
+
+| Property | Default Value | Description | 
+|--|--|--|
+| `osgi.shell.telnet.ip` | 127.0.0.1 | IP Address on which the remote shell is accessible (since 1.0.4). |
+| `osgi.shell.telnet.port` | 6666 | Port on which the remote shell is accessible. |
+| `osgi.shell.telnet.maxconn` | 2 | The maximum number of simultaneous connections. |
+| `osgi.shell.telnet.socketTimeout` | 0 | Sets the SO_TIMEOUT socket option to the given number of milliseconds. The default is no timeout (since 1.0.4). |
+
+<div class="note" markdown="1">
+**Be aware**
+The remote shell does not listen on all interfaces by default; it only listens on the localhost. That is, by default the remote shell is only accessible from the host on which the remote shell is running. To access the system from another host, you have to configure the IP address of the interface to which the remote shell should be attached.
+</div>
+
+## Security Note
+
+This remote shell bundle does not employ any security at all. Thus if no security manager is active in the framework's JVM, then any user connecting to the remote shell has full control over the framework.
+
+To have some minimum level of security ensure the IP Address configured with the `osgi.shell.telnet.ip` property is not publicly accessible.

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-serialization-framework.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-serialization-framework.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-serialization-framework.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-serialization-framework.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,42 @@
+Title: Apache Felix Serialization Framework
+
+# Problem
+
+When you have an object graph that consists of objects that were created by different bundles, serializing and deserializing such a graph becomes a problem, since there is no single bundle that can "see" all (implementation) objects in the graph.
+
+The problem manifests itself for example in Apache Wicket, but also in other applications. The serialization framework is a solution to this problem.
+
+# Design discussion sketch
+
+Made at ApacheCon EU 2009, Robert, Martijn, Felix and Marcel produced the following design on the flipover:
+
+!sf_design.jpg|thumbnail!
+
+# Service design
+
+Basically, we need two services:
+1. The serialization service, that can serialize and deserialize an object graph to an output or input stream.
+1. Helpers that are used to (de)serialize specific objects.
+
+## Serialization Service
+
+
+    interface SerializationService {
+        void serialize(Object o, OutputStream s) throws IOException, UnknownObjectException;
+        Object deserialize(InputStream s) throws IOException, UnknownObjectException;
+    }
+
+
+The actual implementation of this service determines how objects are serialized.
+
+## Serialization Helper
+
+
+    interface SerializationHelper {
+        // TODO
+    }
+
+
+We also discussed adding a special manifest header to a bundle to create a sort of declarative serialization helper. That way the bundle does not need to implement and register the service (if all of them use the same helper anyway).
+
+Helpers in some way need to be linked to a specific serialization service (using an XML serialization with a JSON helper will probably not be what you want).
\ No newline at end of file



Mime
View raw message