| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE- 2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <head> |
| <title>Apache Felix - iPOJO Hello Word (Maven-Based) tutorial</title> |
| <link rel="icon" href="/res/favicon.ico"> |
| |
| <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content="The most powerful component model for OSGi"> |
| |
| |
| <link href="/ipojo/web/bootstrap/css/bootstrap-cerulean.css" rel="stylesheet"> |
| <link href="/ipojo/web/bootstrap/css/bootstrap-responsive.css" rel="stylesheet"> |
| <link href="/ipojo/web/bootstrap/css/font-awesome.min.css" rel="stylesheet"> |
| <link href="/ipojo/web/style.css" rel="stylesheet"> |
| |
| <!-- Overide alert's colors --> |
| <link href="/ipojo/web/bootstrap/css/alert.css" rel="stylesheet"> |
| |
| <link rel="stylesheet" href="/ipojo/web/github.css" type="text/css" media="all"> |
| |
| |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> |
| <script src="/ipojo/web/bootstrap/js/bootstrap.min.js"></script> |
| |
| </head> |
| |
| <body data-spy="scroll" data-target=".subnav"> |
| <div class="navbar navbar-fixed-top navbar-inverse"> |
| <div class="navbar-inner"> |
| <div class="container"> |
| <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </a> |
| <a class="brand" href="/documentation/subprojects/apache-felix-ipojo.html">Apache Felix iPOJO</a> |
| |
| <div class="nav-collapse" id="main-menu"> |
| <ul class="nav" id="main-menu-left"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-news.html">News</a></li> |
| <li><a href="http://felix.apache.org/downloads.cgi">Downloads</a></li> |
| |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="tutorials-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-why-choose-ipojo.html">Why choose iPOJO</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.html">Success stories</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.html">Features</a></li> |
| <li class="divider"></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.html">iPOJO in 10 minutes</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.html">Using Annotations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.html">Maven tutorial</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.html">Advanced tutorial</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.html">Using Distributed OSGi</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.html">Application Composition</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="user-guide-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html">Requiring a service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html">Providing a service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html">Lifecycle management</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html">Configuration</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.html">Introspection</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html">Impacting the lifecycle</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.html">Accessing the Bundle Context</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html">Creating instances</a></li> |
| <li class="divider"></li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">External <em>handlers</em></a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html">Asynchronous communication</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.html">JMX management</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.html">Extender pattern</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html">Whiteboard pattern</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html">Temporal dependencies</a></li> |
| </ul> |
| </li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">Configuration Admin & Factories</a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html">iPOJO and config admin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html">Using the iPOJO Factory service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">Factories and Instances</a></li> |
| </ul> |
| </li> |
| <li class="divider"></li> |
| <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/ipojo-advanced-topics/service-binding-interceptors.html">Service Binding Interceptors</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> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-ipojo-introspection-api.html">Using the introspection API</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.html">Testing components</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.html">Using @Stereotypes</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.html">Eclipse Integration</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-extender-configuration.html">Configuring iPOJO's Extender</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-faq.html">FAQ</a></li> |
| <li class="divider"></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.html">Handler development</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.html">Manipulation Metadata </a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.html">Dive into the iPOJO Manipulation depths</a></li> |
| <li><a href="http://felix.apache.org/ipojo/api/1.12.1">Javadoc</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="tools-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Tools <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.html">Ant Task</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.html">Maven Plugin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.html">Architecture commands</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.html">Online Manipulator</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.html">Webconsole plugin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.html">Apache Karaf Features</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="community-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Community <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-support.html">Support</a></li> |
| <li><a href="http://www.apache.org/">ASF</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="misc-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Misc <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.html">Supported JVMs</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.html">Supported OSGi Implementations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/articles-and-presentations.html">Article & Presentations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/developing-camel-mediators-with-ipojo.html">Developping Camel mediators with iPOJO</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul class="nav pull-right" id="main-menu-right"> |
| <li><a rel="tooltip" target="_blank" href="http://felix.apache.org">Apache Felix <i class="icon-share-alt"></i></a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <div class="content"> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <h1 id="ipojo-hello-world">iPOJO Hello World<a class="headerlink" href="#ipojo-hello-world" title="Permanent link">¶</a></h1> |
| <p><em>This page presents how to use the iPOJO runtime and its associated service component model. The concepts of the service component model are introduced, followed by a simple example that demonstrates the features of iPOJO.</em></p> |
| <h2 id="introduction">Introduction<a class="headerlink" href="#introduction" title="Permanent link">¶</a></h2> |
| <p>iPOJO aims to simplify service-oriented programming on OSGi frameworks; the name iPOJO is an abbreviation for <em>injected POJO</em>. iPOJO provides a new way to develop OSGi service components with the main goal being to simplify service component implementation by transparently managing the dynamics of the environment as well as other non-functional requirements. The iPOJO framework allows developers to more clearly separate functional code (i.e., the POJO) from the non-functional code (i.e., dependency management, service provision, configuration, etc.). iPOJO combines the functional and non-functional aspects at run time. To achieve this, iPOJO provides a simple and extensible service component model based on POJOs.</p> |
| <h2 id="the-pojo-concept">The POJO concept<a class="headerlink" href="#the-pojo-concept" title="Permanent link">¶</a></h2> |
| <p>POJO is an acronym for Plain Old Java Object, but it embodies a concept that the simpler and less intrusive the design of a given framework, the better. The name is used to emphasize that a given object is not somehow special, but is an ordinary Java Object. Martin Fowler, Rebecca Parsons and Josh Mackenzie coined the term POJO in September 2000: "We wondered why people were so against using regular objects in their systems and concluded that it was because simple objects lacked a fancy name. So we gave them one, and it's caught on very nicely." From the developer's perspective, the iPOJO framework strives to only require POJOs in as much as it is possible.</p> |
| <h2 id="ipojo-service-component-overview">iPOJO service component overview<a class="headerlink" href="#ipojo-service-component-overview" title="Permanent link">¶</a></h2> |
| <p>A service component is able to provide and/or require services, where a service is an object that implements a given service interface embodied as a Java interface. In addition, iPOJO introduces a callback concept to notify a component about various state changes.</p> |
| <p>The component is the central concept in iPOJO. In the core iPOJO model, a component describes service dependencies, provided services, and callbacks; this information is recorded in the component's metadata. Then, the second important concept in iPOJO is component instances. A component instances is a special <em>version</em> of the component. By merging component metadata and instance configuration, the iPOJO runtime is able to manage the component, i.e., manage its life cycle, inject required services, publish provided services, discover needed services.</p> |
| <h2 id="a-simple-example">A simple example<a class="headerlink" href="#a-simple-example" title="Permanent link">¶</a></h2> |
| <p>The following is a simple example illustrating how to use the core iPOJO concepts. The example is comprised of two components, one providing a <em>Hello</em> service and one requiring any number of <em>Hello</em> services. The components are packaged into three different bundles using Maven. The <em>hello.service</em> bundle contains the service interface. The <em>hello.impl</em> bundle contains a component implementing the service. The <em>hello.client</em> bundle contains the consumer component.</p> |
| <p>Download the tutorial archive <a href="http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.distribution.maventutorial/1.12.1/org.apache.felix.ipojo.distribution.maventutorial-1.12.1.zip">here</a>. This archive contains a version of Felix (configured with iPOJO), and the projects explained below.</p> |
| <h3 id="preparing-maven-installing-the-tutorial">Preparing Maven & Installing the tutorial<a class="headerlink" href="#preparing-maven-installing-the-tutorial" title="Permanent link">¶</a></h3> |
| <p>The first step is to download and install Maven; the example was created using Maven 2.1+. Once maven is installed on your machine, you can compile the tutorial by unzipping the archive, and by launching the <code>mvn clean install</code> command at the root of tutorial.</p> |
| <p><em>Be aware that Maven outputs a lot of information while it executes and often downloads a lot of required JAR files into its local repository.</em></p> |
| <h3 id="hello-service">Hello Service<a class="headerlink" href="#hello-service" title="Permanent link">¶</a></h3> |
| <p>The first project is the <em>hello.service</em> project. This project contains only the <em>hello</em> service interface. Look at the <code>src/main/java/ipojo/example/hello/Hello.java</code> file:</p> |
| <div class="codehilite"><pre><span class="cm">/**</span> |
| <span class="cm"> * Hello Interface.</span> |
| <span class="cm"> * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a></span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Hello</span> <span class="o">{</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Returns a message like: "Hello $user_name".</span> |
| <span class="cm"> * @param name the name</span> |
| <span class="cm"> * @return the hello message</span> |
| <span class="cm"> */</span> |
| <span class="n">String</span> <span class="nf">sayHello</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>In the project directory, the pom.xml file contains the instructions to build the bundle. The bundle uses the <em>maven-bundle-plugin</em> (see here for more information on this plug-in).</p> |
| <div class="pom"><p><project><br> |
| <modelVersion>4.0.0</modelVersion><br> |
| <packaging>bundle</packaging><br> |
| <font color="#ff0000"><groupId>ipojo.example</groupId></font><br> |
| <font color="#ff0000"> <artifactId>hello.service</artifactId></font><br> |
| <font color="#ff0000"> <version>1.0.0</version></font><br> |
| <font color="#ff0000"> <name>Hello Service</name></font></p> |
| |
| <p><build><br> |
| <plugins><br> |
| <plugin><br> |
| <groupId>org.apache.felix</groupId><br> |
| <artifactId>maven-bundle-plugin</artifactId><br> |
| <version>2.0.1</version><br> |
| <extensions>true</extensions><br> |
| <configuration><br> |
| <instructions><br> |
| <Bundle-SymbolicName><br> |
| ${pom.artifactId}<br> |
| </Bundle-SymbolicName><br> |
| <font color="#ff0000"><Export-Package></font><br> |
| <font color="#ff0000"> ipojo.example.hello</font><br> |
| <font color="#ff0000"> </Export-Package></font><br> |
| </instructions><br> |
| </configuration><br> |
| </plugin><br> |
| </plugins><br> |
| </build></p> |
| |
| <p></project></p></div> |
| |
| <p>Then, the project is ready to be built issuing the following Maven command inside the project directory:</p> |
| <div class="codehilite"><pre>mvn clean install |
| </pre></div> |
| |
| |
| <p>Maven should report that the build was a success; if an error was reported then verify the previous steps. Upon success the <em>Hello</em> service component JAR file is installed into the local Maven repository. A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.</p> |
| <h3 id="hello-service-provider">Hello Service Provider<a class="headerlink" href="#hello-service-provider" title="Permanent link">¶</a></h3> |
| <p>The component implementation of the service is a simple Java class implementing the <em>Hello</em> service interface. The implementation is in the <em>hello.impl</em> project. The file <code>src/main/java/ipojo/example/hello/impl/HelloImpl.java</code> contains the following service implementation:</p> |
| <div class="codehilite"><pre><span class="cm">/**</span> |
| <span class="cm"> * Component implementing the Hello service.</span> |
| <span class="cm"> * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a></span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloImpl</span> <span class="kd">implements</span> <span class="n">Hello</span> <span class="o">{</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Returns an 'Hello' message.</span> |
| <span class="cm"> * @param name : name</span> |
| <span class="cm"> * @return Hello message</span> |
| <span class="cm"> * @see ipojo.example.hello.Hello#sayHello(java.lang.String)</span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="n">String</span> <span class="nf">sayHello</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">{</span> <span class="k">return</span> <span class="s">"hello "</span> <span class="o">+</span> <span class="n">name</span><span class="o">;</span> <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>To manage the component, iPOJO needs some metadata to understand that the component provides the <em>Hello</em> service. iPOJO metadata file is at the root of the <em>hello.impl</em> project ("metadata.xml"). It contains the following metadata (Note: iPOJO also supports a JAR manifest-based syntax):</p> |
| <div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> |
| <span class="nt"><ipojo</span> |
| <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> |
| <span class="na">xsi:schemaLocation=</span><span class="s">"org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd"</span> |
| <span class="na">xmlns=</span><span class="s">"org.apache.felix.ipojo"</span><span class="nt">></span> |
| |
| <span class="nt"><component</span> <span class="na">classname=</span><span class="s">"ipojo.example.hello.impl.HelloImpl"</span> |
| <span class="na">name=</span><span class="s">"HelloProvider"</span><span class="nt">></span> |
| <span class="nt"><provides</span> <span class="nt">/></span> |
| <span class="nt"></component></span> |
| |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"HelloProvider"</span> <span class="na">name=</span><span class="s">"HelloService"</span> <span class="nt">/></span> |
| <span class="nt"></ipojo></span> |
| </pre></div> |
| |
| |
| <p>In the above XML-based metadata, the <em>component</em> element has a mandatory '<em>classname'</em>attribute. This attribute tells iPOJO the implementation class of the component. Since the component in this example provides a service, the component element also specifies a child '<em>provides</em>' element. The '<em>provides</em>' element informs iPOJO that it must manage the publishing of a service. When the '<em>provides</em>' element does not contain an interface attribute, as is the case in this example, iPOJO will expose all implemented interfaces of the component as a service; it is also possible to specify the precise service interface. The '<em>instance</em>' element asks iPOJO to create an instance of your component when the bundle is started.</p> |
| <p>Finally, the <code>pom.xml</code> file contains instructions to build the bundle:</p> |
| <div class="pom"><p><project><br> |
| <modelVersion>4.0.0</modelVersion><br> |
| <packaging>bundle</packaging><br> |
| <font color="red"><groupId>ipojo.example</groupId></font><br> |
| <font color="red"> <artifactId>hello.impl</artifactId></font><br> |
| <font color="red"> <version>1.0.0</version></font></p> |
| |
| <p> <font color="red"><name>Hello Service Provider</name></font></p> |
| |
| <p><font color="red"> <dependencies></font><br> |
| <font color="red"> <dependency> <!--Compilation (i.e. class) dependency on the service interface --></font><br> |
| <font color="red"> <groupId>ipojo.example</groupId></font><br> |
| <font color="red"> <artifactId>hello.service</artifactId></font><br> |
| <font color="red"> <version></font><font color="#ff0000">1.0.0</font><font color="red"></version></font><br> |
| <font color="red"> </dependency></font><br> |
| <font color="red"> </dependencies></font></p> |
| |
| |
| <p> <build><br> |
| <plugins><br> |
| <plugin><br> |
| <groupId>org.apache.felix</groupId><br> |
| <artifactId>maven-bundle-plugin</artifactId><br> |
| <version>2.0.1</version><br> |
| <extensions>true</extensions><br> |
| <configuration><br> |
| <instructions><br> |
| <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName><br> |
| <font color="red"><Private-Package>ipojo.example.hello.impl</Private-Package></font><br> |
| </instructions><br> |
| </configuration><br> |
| </plugin><br> |
| <plugin><br> |
| <groupId>org.apache.felix</groupId><br> |
| <artifactId>maven-ipojo-plugin</artifactId><br> |
| <version>1.12.1</version><br> |
| <executions><br> |
| <execution><br> |
| <goals><br> |
| <goal>ipojo-bundle</goal><br> |
| </goals><br> |
| </execution><br> |
| </executions><br> |
| </plugin><br> |
| </plugins><br> |
| </build><br> |
| </project></p></div> |
| |
| <p>The text highlighted in <span style="color:red">red</span> above indicates the important information related to the project. The first part of the POM file indicates that the packaging format is an iPOJO bundle and also includes some information about the project (name, groupId, and artifactId). This information is not used by iPOJO, but is used by Maven. The rest of the POM file contains the bundle configuration. In the <em>instructions</em> element, you need to enter the bundle name, the bundle description, and the exported packages. The service provider bundle exports the package of <em>Hello</em> interface.</p> |
| <p>Then, the project is ready to be built issuing the following Maven command inside the project directory:</p> |
| <div class="codehilite"><pre>mvn clean install |
| </pre></div> |
| |
| |
| <p>Maven should report that the build was a success; if an error was reported then verify the previous steps. Upon success the <em>Hello</em> service component JAR file is installed into the local Maven repository. A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.</p> |
| <h3 id="hello-service-client">Hello Service Client<a class="headerlink" href="#hello-service-client" title="Permanent link">¶</a></h3> |
| <p>The Hello service consumer is inside the <em>hello.client</em> project. The file <code>src/main/java/ipojo/example/hello/client/HelloClient.java</code> contains the following <em>Hello</em> service client:</p> |
| <div class="codehilite"><pre><span class="kn">package</span> <span class="n">ipojo</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">hello</span><span class="o">.</span><span class="na">client</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">ipojo.example.hello.Hello</span><span class="o">;</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Hello Service simple client.</span> |
| <span class="cm"> * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a></span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloClient</span> <span class="kd">implements</span> <span class="n">Runnable</span> <span class="o">{</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Delay between two invocations.</span> |
| <span class="cm"> */</span> |
| <span class="kd">private</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">int</span> <span class="n">DELAY</span> <span class="o">=</span> <span class="mi">10000</span><span class="o">;</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Hello services.</span> |
| <span class="cm"> * Injected by the container.</span> |
| <span class="cm"> * */</span> |
| <span class="kd">private</span> <span class="n">Hello</span><span class="o">[]</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * End flag.</span> |
| <span class="cm"> * */</span> |
| <span class="kd">private</span> <span class="kt">boolean</span> <span class="n">m_end</span><span class="o">;</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Run method.</span> |
| <span class="cm"> * @see java.lang.Runnable#run()</span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">run</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">while</span> <span class="o">(!</span><span class="n">m_end</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">try</span> <span class="o">{</span> |
| <span class="n">invokeHelloServices</span><span class="o">();</span> |
| <span class="n">Thread</span><span class="o">.</span><span class="na">sleep</span><span class="o">(</span><span class="n">DELAY</span><span class="o">);</span> |
| <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">InterruptedException</span> <span class="n">ie</span><span class="o">)</span> <span class="o">{</span> |
| <span class="cm">/* will recheck end */</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Invoke hello services.</span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">invokeHelloServices</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">for</span> <span class="o">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">m_hello</span><span class="o">.</span><span class="na">length</span><span class="o">;</span> <span class="n">i</span><span class="o">++)</span> <span class="o">{</span> |
| <span class="c1">// Update with your name.</span> |
| <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">m_hello</span><span class="o">[</span><span class="n">i</span><span class="o">]().</span><span class="na">sayHello</span><span class="o">(</span><span class="s">"world"</span><span class="o">));</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Starting.</span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">starting</span><span class="o">()</span> <span class="o">{</span> |
| <span class="n">Thread</span> <span class="n">thread</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Thread</span><span class="o">(</span><span class="k">this</span><span class="o">);</span> |
| <span class="n">m_end</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span> |
| <span class="n">thread</span><span class="o">.</span><span class="na">start</span><span class="o">();</span> |
| <span class="o">}</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Stopping.</span> |
| <span class="cm"> */</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">stopping</span><span class="o">()</span> <span class="o">{</span> |
| <span class="n">m_end</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The <em>Hello</em> service client creates a thread that periodically invokes the available <em>Hello</em> services. The thread starts when at least one <em>Hello</em> service provider is present using iPOJO's call back mechanism. In the client code, to use the <em>hello</em> the component implementation simply declares a field of the type of the service and then simply uses it directly in its code. In this example, it is the m_hello field is declared as the service field; notice that the field is an array of <em>Hello</em>. In iPOJO an array of services represents an aggregate or multiple cardinality dependency, 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").</p> |
| <p>Notice that iPOJO manages service synchronization too. So, the service invocations do not require synchronization blocks. This synchronization is maintained on a per thread basis, where each method that accesses a service is instrumented to attach the given service instance to the thread so that the thread will continue to see the same service instances even across nested method invocations. The thread will not see different service instances until it completely exits from the first method it entered which used a services. Thus, you would not want to access services in the method above, because the thread would always see the same service instance.</p> |
| <p>The component provides two callback methods for its activation and deactivation, starting() and stopping(), respectively. Callbacks are used when the component needs to be informed about a component state change. In iPOJO, the component state is either <em>INVALID</em> (i.e., not all of the component's constraints are satisfied) or <em>VALID</em> (i.e., all of the component's constraints are satisfied). In this example, the starting callback method creates and starts a thread; the stopping callback method stops the thread. The component metadata will instruct iPOJO to invoke these methods when the component's state changes to <em>VALID</em> or <em>INVALID</em> respectively.</p> |
| <p>The iPOJO metadata file describing the component is "metadata.xml" and contains the following metadata:</p> |
| <div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> |
| <span class="nt"><ipojo</span> |
| <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> |
| <span class="na">xsi:schemaLocation=</span><span class="s">"org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd"</span> |
| <span class="na">xmlns=</span><span class="s">"org.apache.felix.ipojo"</span><span class="nt">></span> |
| |
| <span class="nt"><component</span> <span class="na">classname=</span><span class="s">"ipojo.example.hello.client.HelloClient"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hello"</span> <span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">transition=</span><span class="s">"validate"</span> <span class="na">method=</span><span class="s">"starting"</span> <span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">transition=</span><span class="s">"invalidate"</span> <span class="na">method=</span><span class="s">"stopping"</span> <span class="nt">/></span> |
| <span class="nt"><properties></span> |
| <span class="nt"><property</span> <span class="na">field=</span><span class="s">"m_name"</span> <span class="na">name=</span><span class="s">"hello.name"</span> <span class="nt">/></span> |
| <span class="nt"></properties></span> |
| <span class="nt"></component></span> |
| |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"ipojo.example.hello.client.HelloClient"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"hello.name"</span> <span class="na">value=</span><span class="s">"clement"</span> <span class="nt">/></span> |
| <span class="nt"></instance></span> |
| <span class="nt"></ipojo></span> |
| </pre></div> |
| |
| |
| <p>The component element again has the '<em>classname'</em> attribute that refers to the component implementation class. The '<em>requires</em>' element describes the <em>Hello</em> service dependency by simply specifying its associated component field. The '<em>callback'</em>elements describe which method to invoke when the component's state changes. Then the '<em>instance</em>' element asks iPOJO to create an instance of the component (notice that no instance name is provided here, iPOJO will give an instance name to the instance automatically).</p> |
| <p>Finally, the <code>pom.xml</code> file contains instructions to build the bundle:</p> |
| <div class="pom"><p><project><br> |
| <modelVersion>4.0.0</modelVersion><br> |
| <packaging>bundle</packaging><br> |
| <font color="red"><groupId>ipojo.example</groupId></font><br> |
| <font color="red"> <artifactId>hello.client</artifactId></font><br> |
| <font color="red"> <version>1.0.0</version></font><br> |
| <font color="red"> <name>Hello Client</name></font></p> |
| |
| <p><font color="red"> <dependencies></font><br> |
| <font color="red"> <dependency> <!--</font> <font color="red">Compilation (i.e. class) dependency on the service interface --</font><font color="red">></font><br> |
| <font color="red"> <groupId>ipojo.example</groupId></font><br> |
| <font color="red"> <artifactId>hello.service</artifactId></font><br> |
| <font color="red"> <version></font><font color="#ff0000">1.0.0</font><font color="red"></version></font><br> |
| <font color="red"> </dependency></font><br> |
| <font color="red"> </dependencies></font></p> |
| |
| <p> <build><br> |
| <plugins><br> |
| <plugin><br> |
| <groupId>org.apache.felix</groupId><br> |
| <artifactId>maven-bundle-plugin</artifactId><br> |
| <version>2.0.1</version><br> |
| <extensions>true</extensions><br> |
| <configuration><br> |
| <instructions><br> |
| <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName><br> |
| <font color="red"><Private-Package>ipojo.example.hello.client</Private-Package></font><br> |
| </instructions><br> |
| </configuration><br> |
| </plugin><br> |
| <plugin><br> |
| <groupId>org.apache.felix</groupId><br> |
| <artifactId>maven-ipojo-plugin</artifactId><br> |
| <version>1.12.1</version><br> |
| <executions><br> |
| <execution><br> |
| <goals><br> |
| <goal>ipojo-bundle</goal><br> |
| </goals><br> |
| </execution><br> |
| </executions><br> |
| </plugin><br> |
| </plugins><br> |
| </build><br> |
| </project></p></div> |
| |
| <p>The text highlighted in <span style="color:red">red</code> above indicates the information related to the project. The <em>dependencies</em> element tells Maven that the client bundle has a compilation dependency on the service provider bundle. In this case, the client bundle needs the <em>Hello</em> service interface to compile. After building the service provider bundle JAR file, Maven installs it into a local repository on your machine. To resolve compilation dependencies, Maven looks in the local repository to find required JAR files. |
| After the skeleton "pom.xml" file is modified, the project is ready to be built issuing the following Maven command inside the project directory:</p> |
| <div class="codehilite"><pre>mvn clean install |
| </pre></div> |
| |
| |
| <p>Maven should report that the build was a success; if an error was reported then verify the previous steps. Upon success the <em>Hello</em> service component JAR file is installed into the local Maven repository. A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.</p> |
| <h2 id="running-the-example">Running the example<a class="headerlink" href="#running-the-example" title="Permanent link">¶</a></h2> |
| <p>To run the example, start Felix. A distribution of Felix is provided in the felix-1.0.3 directory. This version is configured to launch iPOJO automatically. From the Felix directory, launch the following command to start the framework</p> |
| <div class="codehilite"><pre>java -jar bin/felix.jar |
| </pre></div> |
| |
| |
| <p>You can check installed bundles by using the '<em>ps'</em> command:</p> |
| <div class="codehilite"><pre>-> ps |
| START LEVEL 1 |
| ID State Level Name |
| <span class="o">[</span> 0<span class="o">]</span> <span class="o">[</span>Active <span class="o">]</span> <span class="o">[</span> 0<span class="o">]</span> System Bundle <span class="o">(</span>2.0.5<span class="o">)</span> |
| <span class="o">[</span> 1<span class="o">]</span> <span class="o">[</span>Active <span class="o">]</span> <span class="o">[</span> 1<span class="o">]</span> Apache Felix Bundle Repository <span class="o">(</span>1.4.3<span class="o">)</span> |
| <span class="o">[</span> 2<span class="o">]</span> <span class="o">[</span>Active <span class="o">]</span> <span class="o">[</span> 1<span class="o">]</span> Apache Felix iPOJO <span class="o">(</span>1.12.1<span class="o">)</span> |
| <span class="o">[</span> 3<span class="o">]</span> <span class="o">[</span>Active <span class="o">]</span> <span class="o">[</span> 1<span class="o">]</span> Apache Felix iPOJO Arch Command <span class="o">(</span>1.6.0<span class="o">)</span> |
| <span class="o">[</span> 4<span class="o">]</span> <span class="o">[</span>Active <span class="o">]</span> <span class="o">[</span> 1<span class="o">]</span> Apache Felix Shell Service <span class="o">(</span>1.4.2<span class="o">)</span> |
| <span class="o">[</span> 5<span class="o">]</span> <span class="o">[</span>Active <span class="o">]</span> <span class="o">[</span> 1<span class="o">]</span> Apache Felix Shell TUI <span class="o">(</span>1.4.1<span class="o">)</span> |
| -> |
| </pre></div> |
| |
| |
| <p>iPOJO runtime is the bundle 4. The bundle 5 is a Felix shell command allowing the introspection of iPOJO component instances (see herefor further information).</p> |
| <p>Install the Hello service bundle, the <em>Hello</em> service provider and the client that were created above:</p> |
| <div class="codehilite"><pre>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 |
| </pre></div> |
| |
| |
| <p>By starting the <em>Hello</em> service provider bundle, the client component will automatically be activated. So, the <em>'hello world'</em> messages are displayed.</p> |
| <div class="codehilite"><pre>-> hello world |
| hello world |
| </pre></div> |
| |
| |
| <p>Stop the provider (with the '<em>stop 7</em>' command) and the client will automatically be deactivated since its dependency is no longer valid. If multiple Hello services are deployed, the client will connect to all of them. If you restart the bundle (with the <em>start 7</em> command), the client becomes valid.</p> |
| <p>During these operations, you can use the arch command to check the state of instances.</p> |
| <div class="shell"><p>-> stop 7<br> |
| -> arch<br> |
| Instance ArchCommand -> valid<br> |
| <font color="red">Instance ipojo.example.hello.client.HelloClient-0 -> invalid</font><br> |
| -> arch -instance ipojo.example.hello.client.HelloClient-0<br> |
| instance name="ipojo.example.hello.client.HelloClient-0" <br> |
| component.type="ipojo.example.hello.client.HelloClient" <br> |
| state="<font color="red">invalid</font>" bundle="8"<br> |
| object name="ipojo.example.hello.client.HelloClient@137c60d"<br> |
| <font color="red">handler name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler" state="invalid"</font><br> |
| <font color="red"> </font><font color="red">requires aggregate="true" optional="false" state="resolved" specification="ipojo.example.hello.Hello"</font><br> |
| handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"<br> |
| handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid"<br> |
| -> start 7<br> |
| hello world<br> |
| -> arch<br> |
| Instance ArchCommand -> valid<br> |
| <font color="red">Instance ipojo.example.hello.client.HelloClient-0 -> valid</font><br> |
| Instance HelloService -> valid<br> |
| -> arch -instance ipojo.example.hello.client.HelloClient-0<br> |
| instance name="ipojo.example.hello.client.HelloClient-0" <br> |
| component.type="ipojo.example.hello.client.HelloClient"<br> |
| state="valid" bundle="8"<br> |
| object name="ipojo.example.hello.client.HelloClient@137c60d"<br> |
| <font color="red">handler name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler" state="valid"</font><br> |
| <font color="red"> </font><font color="red">requires aggregate="true" optional="false" state="resolved" specification="ipojo.example.hello.Hello"</font><br> |
| <font color="red"> </font> <font color="red">uses service.id="38" instance.name="HelloService"</font><br> |
| handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"<br> |
| handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid"</p></div> |
| |
| <h2 id="conclusion">Conclusion<a class="headerlink" href="#conclusion" title="Permanent link">¶</a></h2> |
| <p>We saw how to use easily iPOJO to build service-oriented components. Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org">users-subscribe@felix.apache.org</a>; after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org">users@felix.apache.org</a>.</p> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <div class="container"> |
| <footer id="footer"> |
| <div class="row"> |
| <div class="trademarkFooter span7"> |
| Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project |
| logo are trademarks of The Apache Software Foundation. All other marks mentioned |
| may be trademarks or registered trademarks of their respective owners. |
| </div> |
| <div class="timestamp span3 offset2"> |
| Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000 |
| </div> |
| </div> |
| </footer> |
| </div> |
| </body> |
| |
| <script type="text/javascript"> |
| var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); |
| document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); |
| </script> |
| |
| <script type="text/javascript"> |
| try{ |
| var pageTracker = _gat._getTracker("UA-1518442-4"); |
| pageTracker._trackPageview(); |
| } catch(err) {} |
| </script> |
| |
| </html> |
