You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by cl...@apache.org on 2013/10/07 20:04:27 UTC
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/
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>