svn commit: r1571278 - in /felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide: apache-felix-ipojo-instances.mdtext ipojo-advanced-topics/ipojo-factory-service.mdtext

[gu...@apache.org]

Author: guillaume
Date: Mon Feb 24 13:20:49 2014
New Revision: 1571278

URL: http://svn.apache.org/r1571278
Log:
FELIX-4419 Open access to InstanceDeclaration and TypeDeclaration

* New API documentation

Modified:
    felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.mdtext
    felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.mdtext

Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.mdtext?rev=1571278&r1=1571277&r2=1571278&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.mdtext Mon Feb 24 13:20:49 2014
@@ -17,6 +17,7 @@ iPOJO provides several ways to create in
 * using <instance> in the XML metadata
 * using the iPOJO Factory service
 * using the OSGi Configuration Admin
+* using the `DeclarationBuilderService`
 
 
 @Instantiate
@@ -351,3 +352,44 @@ Disposing instances
 -------------------
 To dispose an instance, just call the `delete` method on the configuration object you used to configure the instance.
 
+Creating instances with declarations
+======================================
+
+Declarations offer a nice way to declares instances in a programmatic way. If not retracted by hand,
+they're bound to the declaring bundle lifecycle (i.e. are unregistered when the bundle is not `ACTIVE`
+anymore).
+
+Declarations can be build using the `DeclarationBuilderService` (see interface below). Instances (of
+components), types (components) and iPOJO extensions can also be build using this service.
+
+    :::java
+    public interface DeclarationBuilderService {
+        InstanceBuilder newInstance(String type);
+        InstanceBuilder newInstance(String type, String name);
+        InstanceBuilder newInstance(String type, String name, String version);
+        DeclarationHandle newExtension(String name, FactoryBuilder builder);
+        DeclarationHandle newType(Element description);
+    }
+
+
+Instances created through declaration can indeed be configured.
+
+	:::java
+    // Obtain the service through the service registry
+    DeclarationBuilderService service = ...
+
+    // Get a fresh instance builder
+    InstanceBuilder builder = service.newInstance("my-factory");
+
+    DeclarationHandle handle = builder.name("a-unique-name") // Make sure name is unique for the expected type
+                                      .configure()
+                                          .property("a-property", "a-value")
+                                          .property("another-property", "another-value")
+                                          .build();
+
+    // Push the InstanceDeclaration service in the registry
+    handle.publish();
+
+The builder ultimately produces handles to declarations. Handles are the live link to the underlying
+declarations: service publication and un-registration are done through the `handle.publish()` and
+`handle.retract()` methods. Declaration status (is it bound or not) is also accessible with `handle.getStatus()`.

Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.mdtext?rev=1571278&r1=1571277&r2=1571278&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.mdtext Mon Feb 24 13:20:49 2014
@@ -111,16 +111,35 @@ You can't delete an instance directly fr
 ### Observing the factory state
 As stated above, factory objects have a state. We already saw how to retrieve the current state of the factory. You can also register a [FactoryStateListener](http://felix.apache.org/ipojo/api/{{ipojo.release}}/org/apache/felix/ipojo/architecture/FactoryStateListener.html) to be notified when the state changes. The methods `addFactoryStateListener` and `removeFactoryStateListener` let you respectively register and unregister the listener.
 
-## Declaration publication vs. Programatic creation
+## Declaration publication vs. Programmatic creation
 
 This page has explained how to create an instance from the Factory service. However, when the factory leaves or become invalid your instance is disposed. The instance is **not** recreated when the factory comes back or is revalidated.
 
-To avoid to have to listen and manage these events, you can use an [InstanceDeclaration](http://felix.apache.org/ipojo/api/{{ipojo.release}}/org/apache/felix/ipojo/architecture/InstanceDeclaration.html). An instance declaration is a service you publish to instruct iPOJO to create an instance and manage its life. 
+To avoid to have to listen and manage these events, you can use an [InstanceDeclaration](http://felix.apache.org/ipojo/api/{{ipojo.release}}/org/apache/felix/ipojo/architecture/InstanceDeclaration.html).
+An instance declaration is a service you publish to instruct iPOJO to create an instance
+and manage its lifecycle. `InstanceDeclaration` are created through the `DeclarationBuilderService`
+(since 1.12):
 
 	:::java
-	InstanceDeclaration declaration = new DefaultInstanceDeclaration(bundleContext, "my-factory", configuration);
-	declaration.start();
+    // Obtain the service through the service registry
+    DeclarationBuilderService service = ...
 
-In this snippet, we create an instance declaration _declaring_ an instance of `my-factory` with the given (potentially `null`) configuration. Notice that you must provide an OSGi bundle context. Once created, call the `start` method to register the service and delegate the task to iPOJO.
+    // Get a fresh instance builder
+    InstanceBuilder builder = service.newInstance("my-factory");
 
-Call the `stop` method on the instance declaration to dispose the instance.
+    DeclarationHandle handle = builder.name("a-unique-name") // Make sure name is unique for the expected type
+                                      .configure()
+                                          .property("a-property", "a-value")
+                                          .property("another-property", "another-value")
+                                          .build();
+
+    // Push the InstanceDeclaration service in the registry
+    handle.publish();
+
+In this snippet, we've registered a named `InstanceDeclaration` service for the `my-factory` component type, we've
+created a handle though an `InstanceBuilder` object. The builder helps to configure and produce an
+InstanceDeclaration that is controllable through the handle. By default, the declaration service will be registered with
+the BundleContext of the user (this is configurable with the `context(BundleContext)` method). Once
+created, call the `publish` method to register the declaration service and let iPOJO do its usual work.
+
+Call the `retract` method on the handle to dispose the service.