iPOJO Hello World

简单的样例
下面的简单样例将演示如何使用核心iPOJO概念。样例由2个组件组成。一个提供了Hello服务而另一个使用多个hello服务。这些组件使用Maven被打包成3个不同的bundle。hello.service服务包包含了服务的接口（接口和实现分离）。hello.impl服务包包含了一个实现服务的组件。hello.client服务包包含服务消费组件。

准备Maven 安装示例
第一步，下载并安装Maven;本例子使用Maven 2.2.0来创建。当你机器上安装了Maven后，你就可以编译本例子解压后的项目了，并在项目的根目录下用命令"mvn clean install"

注意：当Maven执行时会输出一些信息，并会经常下载一些需要的JAR文件到本地库中

Hello Service
第一个项目是hello.service，项目仅包含了一个服务接口。
$ mvn archetype:create -DgroupId=iPOJOTutorial -DartifactId=hello.service -Dversion=1.0.0 -DpackageName=ipojo.example.hello

使用mvn创建hello.service项目.
创建src/main/java/ipojo/example/hello/Hello.java
package ipojo.example.hello;
/**
* Hello Interface.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface Hello {

/**
* Returns a message like: "Hello $user_name".
* @param name the name
* @return the hello message
*/
String sayHello(String name);
}


在生成的pom.xml文件中修改和添加如下内容：
<packaging>bundle</packaging>

<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>1.4.3</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-SymbolicName>
${pom.artifactId}
</Bundle-SymbolicName>
<Export-Package>
ipojo.example.hello
</Export-Package>
</instructions>
</configuration>
</plugin>
</plugins>
</build>

进入hello.service根目录，输入命令:
mvn clean install


Maven报告构建成功，在根目录下的target目录下你就可以看到生成的bundle了。可以查看该jar文件中的META-INF下的MANIFEST.MF文件中是否有Export-Package、Bundle-*等关键词，如果有说明我们构建输出的是bundle。当然install命令也将我们的bundle发布到本地库中了。本地库方面的知识，读者可自行阅读Maven方面的书籍。


Hello 服务供应者
服务的实现组件是一个普通的实现了Hello Service接口的类。服务组件的实现包含在hello.impl项目中。首先我们还是使用mvn来帮助我们构建项目的骨架。


输入：mvn archetype:create -DgroupId=iPOJOTutorial -Dar
tifactId=hello.impl -Dversion=1.0.0 -DpackageName=ipojo.example.hello.impl。

服务实现如下：
package ipojo.example.hello.impl;
/**
* Component implementing the Hello service.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
import ipojo.example.hello.Hello;
public class HelloImpl implements Hello {

/**
* Returns an 'Hello' message.
* @param name : name
* @return Hello message
* @see ipojo.example.hello.Hello#sayHello(java.lang.String)
*/
public String sayHello(String name) { return "hello " + name; }
}

为了管理组件，iPOJO还需要metadata来描述组件提供的Hello服务。iPOJO metadata文件在hello.impl项目的根目录下，名字为metadata.xml。它包含了一下元数据（iPOJO也支持JAR的mainifest风格的语法）

<iPOJO>
<component className="ipojo.example.hello.impl.HelloImpl" name="HelloProvider">
<provides />
</component>
<instance component="HelloProvider" name="HelloService" />
</iPOJO>


pom.xml文件内容如下：
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>iPOJOTutorial</groupId>
<artifactId>hello.impl</artifactId>
<packaging>bundle</packaging>
<version>1.0.0</version>
<name>hello.impl</name>
<url>http://maven.apache.org</url>
<dependencies>

<dependency> <!--Compilation (i.e. class) dependency on the service interface -->
<groupId>iPOJOTutorial</groupId>
<artifactId>hello.service</artifactId>
<version>1.0.0</version>
</dependency>

<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>

<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>1.4.3</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
<Private-Package>ipojo.example.hello.impl</Private-Package>
</instructions>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-ipojo-plugin</artifactId>
<version>1.2.0</version>
<executions>
<execution>
<goals>
<goal>ipojo-bundle</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</dependencies>

</project>

本项目首先依赖接口，所以比上一个项目增加了一个<dependency>。同时还增加了一个maven-ipojo-plugin。

当上面的工作完成并进入项目的根目录后，我们就可以使用mvn clean install来构建项目了。

成功构建bundle后，在bundle中的MANIFEST.MF内容如下：
Manifest-Version: 1.0
Private-Package: ipojo.example.hello.impl
iPOJO-Components: component { $name="HelloProvider" $classname="ipojo.
example.hello.impl.HelloImpl" $architecture="true" provides { }manipu
lation { method { $name="$init" }method { $arguments="{java.lang.Stri
ng}" $name="sayHello" $return="java.lang.String" }interface { $name="
ipojo.example.hello.Hello" }}}instance { $component="HelloProvider" $
name="HelloService" }
Built-By: zhangcm
Tool: Bnd-0.0.255
Bundle-Name: hello.impl
Created-By: Apache Maven Bundle Plugin & iPOJO
Bundle-Version: 1.0.0
Build-Jdk: 1.6.0_06
Bnd-LastModified: 1247623899280
Bundle-ManifestVersion: 2
Import-Package: org.osgi.service.log;version=1.3, org.apache.felix.ipo
jo.architecture;version= 1.2.0, ipojo.example.hello, org.apache.felix
.ipojo;version= 1.2.0, org.osgi.service.cm;version=1.2
Bundle-SymbolicName: hello.impl


Hello Service 客户端
Hello服务消费在项目hello.client中。使用mvn创建该项目：

mvn archetype:create -DgroupId=iPOJOTutorial -DartifactId=hello.client -Dversion=1.0.0 -DpackageName=ipojo.example.hello.client。
客户端代码如下：

package ipojo.example.hello.client;

import ipojo.example.hello.Hello;

/**
* Hello Service simple client.
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public class HelloClient implements Runnable {

/**
* Delay between two invocations.
*/
private static final int DELAY = 10000;

/**
* Hello services.
* Injected by the container.
* */
private Hello[] m_hello; // Service Requirement

/**
* End flag.
* */
private boolean m_end;

/**
* Name property.
* Injected by the container.
* */
private String m_name;

/**
* Run method.
* @see java.lang.Runnable#run()
*/
public void run() {
while (!m_end) {
try {
invokeHelloServices();
Thread.sleep(DELAY);
} catch (InterruptedException ie) {
/* will recheck end */
}
}
}

/**
* Invoke hello services.
*/
public void invokeHelloServices() {
for (int i = 0; i < m_hello.length; i++) {
System.out.println(m_hello[i].sayHello(m_name));
}
}

/**
* Starting.
*/
public void starting() {
Thread thread = new Thread(this);
m_end = false;
thread.start();
}

/**
* Stopping.
*/
public void stopping() {
m_end = true;
}
}


Hello Service 客户端创建一个线程，间断性地调用Hello服务。当至少存在一个hello服务的供应者，iPOJO回调机制
会调用客户端的starting方法来启动线程。在客户端代码中，为了使用hello服务的实现组件，只需要简单地定义服务接口类型的字段。在本项目中，那它就是m_hello。请注意m_hello字段是一个Hello数组。在iPOJO中服务数组表示聚合依赖。whereas if a scalar value represents a singular or unary cardinality dependency. In other words, for a singular dependency simply remove the array brackets from the example (e.g., HelloService m_hello[]. After declaring a field for the service, the rest of the component code can simply assume that the service field will be initialized, e.g., m_hello[i].sayHello("world").

注意：iPOJO也管理服务的同步。因此，服务的调用时不需要同步块（synchronization）。这种同步是基于每线程基础上的。每一种方法访问的服务是附加在线程上的给定的服务实例，因此线程将会一直能看到同一个服务实例，甚至跨入嵌套方法调用。线程除了完全从第一个它进入的服务方法中退出为至。。因此，你不需要在run()方法之外存取服务，因为线程将永远看到相同的服务实例。

本组件提供了2个回调方法starting() stopping()分别用于激活和去激活。当组件需要得到有关组件状态改变的通知，就需要用到回调了。在iPOJO中，组件只有2个状态INVALID（组件的约束不满足，如依赖的服务不存在）和VALID（组件的约束满足）。在本例中，starting 回调方法创建并开启线程。stopping回调方法停止线程。组件元数据指示iPOJO调用这两个方法，当组件状态在VALID或者INVALID变化时。


在本项目的根目录下，创建metadata.xml文件，内容如下：
<?xml version="1.0" encoding="UTF-8"?>
<iPOJO>
<component className="ipojo.example.hello.client.HelloClient"
architecture="true">
<requires field="m_hello" />
<callback transition="validate" method="starting" />
<callback transition="invalidate" method="stopping" />
<properties>
<property field="m_name" name="hello.name" />
</properties>
</component>
<instance component="ipojo.example.hello.client.HelloClient">
<property name="hello.name" value="clement" />
</instance>
</iPOJO>

pom.xml文件内容如下：
<project>
<modelVersion>4.0.0</modelVersion>
<packaging>bundle</packaging>
<groupId>iPOJOTutorial</groupId>
<artifactId>hello.client</artifactId>
<version>1.0.0</version>
<name>Hello Client</name>

<dependencies>
<dependency> <!-- Compilation (i.e. class) dependency on the service interface -->
<groupId>iPOJOTutorial</groupId>
<artifactId>hello.service</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<version>1.4.3</version>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
<Private-Package>ipojo.example.hello.client</Private-Package>
</instructions>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-ipojo-plugin</artifactId>
<version>1.2.0</version>
<executions>
<execution>
<goals>
<goal>ipojo-bundle</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

构建客户端：mvn clean install




示例运行：
启动Felix运行本示例。
java -jar bin/felix.jar
Welcome to Felix.
=================

-> ps
START LEVEL 1
ID State Level Name
[ 0] [Active ] [ 0] System Bundle (1.4.1)
[ 1] [Active ] [ 1] Apache Felix Shell Service (1.0.2)
[ 2] [Active ] [ 1] Apache Felix Shell TUI (1.0.2)
[ 3] [Active ] [ 1] Apache Felix Bundle Repository (1.2.1)
[ 4] [Active ] [ 1] Apache Felix iPOJO (1.2.0)
[ 5] [Active ] [ 1] Apache Felix iPOJO Arch Command (1.2.0)
->


start file:../hello.service/target/hello.service-1.0.0.jar
start file:../hello.impl/target/hello.impl-1.0.0.jar
start file:../hello.client/target/hello.client-1.0.0.jar