felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clem...@apache.org
Subject svn commit: r1530016 - in /felix/site/trunk: content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ templates/
Date Mon, 07 Oct 2013 18:04:27 GMT
Author: clement
Date: Mon Oct  7 18:04:27 2013
New Revision: 1530016

URL: http://svn.apache.org/r1530016
Log:
Add documentation about the difference between service controllers and instance controllers.

Added:
    felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.mdtext
Modified:
    felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.mdtext
    felix/site/trunk/templates/ipojo.html

Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.mdtext?rev=1530016&r1=1530015&r2=1530016&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.mdtext
(original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.mdtext
Mon Oct  7 18:04:27 2013
@@ -11,14 +11,14 @@ Title: How to use iPOJO Annotations
 
 ## Getting iPOJO Annotations:
 
-iPOJO Annotations are defines inside the org.apache.felix.ipojo.annotations project. You
can download the Jar file of this project from the [download]({{ refs.download.path }}) page.
Sources are available on the [Felix trunk|http://felix.apache.org/site/sourcecode.html].
-Once added to your class path / build path / dependencies, you can use the annotations as
normal annotations. These annotations are automatically processed by the iPOJO manipulator.
+iPOJO Annotations are defines inside the `org.apache.felix.ipojo.annotations project`. You
can download the Jar file of this project from the [download]({{ refs.download.path }}) page.
Sources are available on the [Felix trunk|http://felix.apache.org/site/sourcecode.html].
+Once added to your class path / build path / dependencies, you can use the annotations as
normal annotations. These annotations are automatically processed by the iPOJO manipulator,
and do **not** need to be deployed at runtime.
 
-### In Eclipse
+### With Eclipse (or any other IDE_
 
 Add the org.apache.felix.ipojo.annotations jar file in your build path. Do not forget to
use a Java compiler accepting annotations (1.5 or higher).
 
-### In Maven
+### With Maven
 
 Add the following dependency:
 
@@ -26,7 +26,7 @@ Add the following dependency:
     <dependency>
           <groupId>org.apache.felix</groupId>
           <artifactId>org.apache.felix.ipojo.annotations</artifactId>
-          <version>1.8.0</version>
+          <version>{{ipojo.release}}</version>
     </dependency>
 
 Moreover, you need to set that the source code and the target code are Java 1.5 code. To
achieve this, just add the following plugin in your plugins section:
@@ -42,7 +42,7 @@ Moreover, you need to set that the sourc
     </plugin>
 
 
-### In Ant
+### With Ant
 
 Just add the org.apache.felix.ipojo.annotations jar file  in your class path.
 
@@ -92,37 +92,37 @@ Then, it uses the requires annotation to
     
     import ipojo.example.hello.Hello;
     
-    @Component(name="AnnotedHelloClient", immediate=true)
+    @Component(name="AnnotatedHelloClient", immediate=true)
+    @Instantiate
     public class HelloClient implements Runnable {
     
     @Requires
-    private Hello[] m_hello; // Service Dependency
+    private Hello[] m_hello;
     
     private final static int DELAY=10000;
     private boolean end;
     
      public void run() {
         while (!end) {
-                   try {
-    		invoke();
-                    Thread.sleep(DELAY);
-                  } catch (InterruptedException ie) { }
-                  /* will recheck end */
+			try {
+    			invoke();
+                Thread.sleep(DELAY);
+        	} catch (InterruptedException ie) { }
          }
     }
     
     public void invoke() {
     	for (int i = 0; i < m_hello.length; i++) { 
               System.out.println(m_hello[i].
-                 sayHello("Clement")); 
+                 sayHello("iPOJO")); 
             }
     }
     
      @Validate
      public void starting() {    
-        Thread T = new Thread(this);     
+        Thread thread = new Thread(this);     
         end = false;     
-        T.start(); 
+        thread.start(); 
      }
     
      @Invalidate

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.mdtext?rev=1530016&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.mdtext
(added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.mdtext
Mon Oct  7 18:04:27 2013
@@ -0,0 +1,73 @@
+# Instance Controller or Service Controller ?
+
+When the component implementation needs to impact the instance container, it uses _controllers_
on Boolean fields. iPOJO provides two controllers:
+
+* Instance Lifecycle Controller (`@Controller`)
+* Service Lifecycle Controller (`@ServiceController`)
+
+This page explains the differences between the two kinds of controllers.
+
+## The Instance Lifecycle Controller
+
+The instance lifecycle controller impacts the instance state. Such controller must only be
used if the instance code has detected an irremediable situation, where the instance cannot
behave correctly.
+
+Such controller is generally used when the component code:
+
+* check the configuration
+* has caught an error
+
+Instance Lifecycle Controller cannot be initialized, and generally are only set to `false`:
+
+	:::java
+	@Component
+	public class MyComponent {
+
+		@Controller
+		private boolean controller;
+
+		@Property(name="my-property")
+		public void setMyProperty(String value) {
+			if (! ACCEPTABLE_VALUES.contains(value) {
+					// Let's image that if the given 
+					// value is not acceptable, we invalidate
+					// the instance
+					controller = false;
+			}
+		}
+	}
+
+When set to `false`:
+
+* the service exposed by the instance are withdrawn from the service registry
+* the `@Invalidate` callback is called
+
+## The service lifecycle controller
+
+The service lifecycle controller impacts only the services exposed by the instance. It is
used when the component implementation decides whether or not to publish the services. 
+
+Unlike the instance lifecycle controller, such controller can:
+
+* be set to `false` at startup (to not publish the services by default).
+* fluctuate between `true` and `false` to reflect the decision of the component implementation
to publish or not the services.
+
+	:::java
+	@Component
+	@Provides
+	public class MyComponent implements MyService {
+
+		// Service not published by default
+		@ServiceController(value=false)
+		private boolean controller;
+	
+		@Validate
+		public void initialize() {
+			//...
+			// publish the service once the initialization
+			// is completed.
+			controller = true;
+		}
+	}
+
+When the controller is set to `true`, the `@PostRegistration` callback is called. When it
is set to `false` the `@PostUnregistration` callback is called. In both cases, the service
is already registered or unregistered when the callback is invoked.
+
+Notice that a `@ServiceController` controls all exposed services by default, but can be restricted
to specific service interface with the `specification` attribute.

Modified: felix/site/trunk/templates/ipojo.html
URL: http://svn.apache.org/viewvc/felix/site/trunk/templates/ipojo.html?rev=1530016&r1=1530015&r2=1530016&view=diff
==============================================================================
--- felix/site/trunk/templates/ipojo.html (original)
+++ felix/site/trunk/templates/ipojo.html Mon Oct  7 18:04:27 2013
@@ -107,6 +107,7 @@
                                 <li class="dropdown-submenu">
                                     <a tabindex="-1" href="#">Advanced topics</a>
                                     <ul class="dropdown-menu">
+                                        <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html">Instance
vs. Service Controllers</a></li>
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/using-xml-schemas.html">XML
Schemas</a></li>
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.html">Using
the iPOJO API</a></li>
                                         <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html">Constructing
service objects with factory methods</a></li>



Mime
View raw message