| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd";> |
| <!-- |
| 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. |
| --> |
| <html> |
| <head> |
| <link rel="shortcut icon" href="http://aries.apache.org/images/favicon.ico"></link> |
| <link type="text/css" rel="stylesheet" href="http://aries.apache.org/resources/site.css"></link> |
| </script><script src="http://aries.apache.org/resources/menus.js" language="javascript" type="text/javascript"></script> |
| <meta name="keywords" content="..."/> |
| <meta name="description" content="..." /> |
| <title> |
| Apache Aries - BlueprintHelloWorldTutorial |
| </title> |
| </head> |
| <body onload="SetMenu()"> |
| |
| <table width="100%" cellpadding="0" cellspacing="0"> |
| <tr width="100%"> |
| <td id="cell-0-0" colspan="2"> </td> |
| <td id="cell-0-1"> </td> |
| <td id="cell-0-2" colspan="2"> </td> |
| </tr> |
| <tr width="100%"> |
| <td id="cell-1-0"> </td> |
| <td id="cell-1-1"> </td> |
| <td id="cell-1-2"> |
| <div style="padding: 5px;"> |
| <div id="banner"> |
| <!-- Banner --> |
| <table border="0" cellpadding="0" cellspacing="0" width="100%"> |
| <tr> |
| <td align="left" class="topbardiv" nowrap=""> |
| <a href="http://aries.apache.org/" title="Apache Aries"> <img border="0" src="http://aries.apache.org/images/Arieslogo_Horizontal.gif"> </a> |
| </td> |
| <td align="right" nowrap=""> |
| <a href="http://www.apache.org/" title="The Apache Software Foundation"> <img border="0" src="http://aries.apache.org/images/apache_feather.png"> </a> |
| </td> |
| </tr> |
| </table> |
| <!-- Banner --> |
| </div> |
| </div> |
| <div id="top-menu"> |
| <table border="0" cellpadding="1" cellspacing="0" width="100%"> |
| <tr> |
| <td> |
| <div align="left"> |
| <!-- Breadcrumbs --> |
| <!-- Breadcrumbs --> |
| </div> |
| </td> |
| <td> |
| <div align="right"> |
| <!-- Quicklinks --> |
| <DIV style="padding: 5px 5px 0px 25px;"> |
| <FORM action="http://www.google.com/search" method="get" style="font-size: 10px;"> |
| <A href="http://www.apache.org/licenses/LICENSE-2.0.html" class="external-link" rel="nofollow">License</A> |
| <INPUT name="ie" type="hidden" value="UTF-8"></INPUT> |
| <INPUT name="oe" type="hidden" value="UTF-8"></INPUT> |
| <INPUT maxlength="255" name="q" size="15" type="text" value></INPUT> |
| <INPUT name="btnG" type="submit" value="Search"></INPUT> |
| <INPUT name="domains" type="hidden" value="aries.apache.org"></INPUT> |
| <INPUT name="sitesearch" type="hidden" value="aries.apache.org"></INPUT> |
| </FORM> |
| </DIV> |
| <!-- Quicklinks --> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </td> |
| <td id="cell-1-3"> </td> |
| <td id="cell-1-4"> </td> |
| </tr> |
| <tr width="100%"> |
| <td id="cell-2-0" colspan="2"> </td> |
| <td id="cell-2-1"> |
| <table> |
| <tr height="100%" valign="top"> |
| <td height="100%"> |
| <div id="wrapper-menu-page-right"> |
| <div id="wrapper-menu-page-top"> |
| <div id="wrapper-menu-page-bottom"> |
| <div id="menu-page"> |
| <!-- NavigationBar --> |
| <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> |
| <div onclick="SwitchMenu('documentation')" id="documentationTitle" class="menutitle">Documentation</div> |
| |
| <div id="documentation" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="/documentation/integrators-guide.html">Integrators Guide</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/documentation/articles.html">Articles</a> |
| </div> |
| <div class="menuitem"> |
| <a href="https://svn.apache.org/repos/asf/aries/slides/">Slides</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/documentation/tutorials.html">Tutorials</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/documentation/tools.html">Tools</a> |
| </div> |
| </div> |
| |
| <div onclick="SwitchMenu('modules')" id="modulesTitle" class="menutitle">Modules</div> |
| |
| <div id="modules" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="/modules/samples.html">Samples</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/async-svcs.html">Asynchronous Services</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/blueprint.html">Blueprint</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/blueprint-maven-plugin.html">Blueprint-maven-plugin</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/blueprintannotation.html">Blueprint Annotations</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/blueprintnoosgi.html">Blueprint No-OSGi</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/blueprintweb.html">Blueprint Web</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/esaanttask.html">ESA Ant Task </a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/ebamavenpluginproject.html">EBA Maven Plugin </a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/esamavenpluginproject.html">ESA Maven Plugin </a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/jmx.html">JMX</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/jndiproject.html">JNDI</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/jpaproject.html">JPA</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/transactioncontrol.html">Transaction Control Service</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/transactionsproject.html">Transactions</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/rsa.html">Remote Service Admin (RSA)</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/spi-fly.html">SPI Fly</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/subsystems.html">Subsystems</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/modules/applications.html">Applications (obsolete)</a> |
| </div> |
| </div> |
| |
| <div onclick="SwitchMenu('downloads')" id="downloadsTitle" class="menutitle">Downloads</div> |
| |
| <div id="downloads" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="/downloads/currentreleases.html">Current Releases</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/downloads/testresults.html">Compliance Tests</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/downloads/archived-releases.html">Archived Releases</a> |
| </div> |
| </div> |
| |
| <div onclick="SwitchMenu('community')" id="communityTitle" class="menutitle">Community</div> |
| |
| <div id="community" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="/community/resources.html">Community Resources</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/community/gettinginvolved.html">Getting Involved</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/community/people.html">Who we are</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/community/boardreports.html">Board Reports</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/community/logos.html">Logos for Users</a> |
| </div> |
| </div> |
| |
| <div onclick="SwitchMenu('development')" id="developmentTitle" class="menutitle">Development</div> |
| |
| <div id="development" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="/development/buildingaries.html">Building Aries </a> |
| </div> |
| <div class="menuitem"> |
| <a href="/development/guidelines.html">Cording Guidelines</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/development/architecture.html">Architecture</a> |
| </div> |
| <div class="menuitem"> |
| <a href="/development/releasingaries.html">Releasing Aries </a> |
| </div> |
| <div class="menuitem"> |
| <a href="/development/compliancetesting.html">OSGi Compliance Tests </a> |
| </div> |
| <div class="menuitem"> |
| <a href="/development/maintainingthewebpages.html">Web Site Maintenance </a> |
| </div> |
| </div> |
| |
| <div onclick="SwitchMenu('sponsorship')" id="sponsorshipTitle" class="menutitle">Sponsorship</div> |
| |
| <div id="sponsorship" class="menuitemgroup"> |
| <div class="menuitem"> |
| <a href="http://www.apache.org/foundation/thanks.html">Thanks</a> |
| </div> |
| <div class="menuitem"> |
| <a href="http://www.apache.org/foundation/sponsorship.html">Sponsoring Apache</a> |
| </div> |
| </div> |
| <!-- NavigationBar --> |
| </div> |
| </div> |
| </div> |
| </div> |
| </td> |
| <td height="100%" width="100%"> |
| <!-- Content --> |
| <div class="wiki-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> |
| <p><a name="BlueprintHelloWorldTutorial-Blueprinttutorial"></a></p> |
| <h1 id="blueprint-tutorial">Blueprint tutorial<a class="headerlink" href="#blueprint-tutorial" title="Permanent link">¶</a></h1> |
| <p><a name="BlueprintHelloWorldTutorial-Introduction"></a></p> |
| <h3 id="introduction">Introduction<a class="headerlink" href="#introduction" title="Permanent link">¶</a></h3> |
| <p>This tutorial is designed for people who are starting to use the Apache |
| Aries Blueprint implementation. After you have worked through the tutorial |
| you will |
| - be able to run a very simple piece of code in the Aries Blueprint container |
| - understand bean, service and reference definitions in Blueprint</p> |
| <p>The tutorial assumes a basic working knowledge of Java development, Eclipse |
| and some understanding of OSGi.</p> |
| <p>In order to work through the tutorial you will need to do checkout and |
| build copy of Aries, the instructions are <a href="/development/buildingaries.html">here</a> |
| . This tutorial assumes that you have built Aries and imported the |
| samples/helloworld projects into Eclipse. </p> |
| <p><a name="BlueprintHelloWorldTutorial-TheAPI,ServerandClientprojects"></a></p> |
| <h3 id="the-api-server-and-client-projects">The API, Server and Client projects<a class="headerlink" href="#the-api-server-and-client-projects" title="Permanent link">¶</a></h3> |
| <p>When you have checked out and built the Aries code your workspace will |
| contain the four projects highlighted in the picture below. This is a |
| screen shot taken from my Eclipse package explorer: <br> |
| <br> |
| <img alt="hw1" src="HW1.png" /> |
| <br> |
| <br> |
| The project called org.apache.aries.samples.helloworld.blueprint.assembly |
| contains no Java code and is just used to pull together the minimal OSGi |
| platform that is needed to run the sample. |
| Expanding the org.apache.aries.samples.helloworld.blueprint.api project |
| shows this: |
| <br> |
| <br> |
| <img alt="hh2" src="HW2.png" /> |
| <br> |
| <br> |
| There are two interesting features of this project, the |
| HelloWorldService.java interface and empty META-INF directory. |
| HelloWorldService.java is the interface for the Helloworld service. It is |
| good OSGi practice to keep interfaces and implementation classes in |
| separate bundles. This allows implementations to be replaced independently |
| of their interfaces. The META-INF directory is where you would expect to |
| see a file called MANIFEST.MF. You don't see it because we are using a |
| Maven plugin (look at the pom.xml) to generate the bundle manifest |
| automatically.</p> |
| <p>Expanding the org.apache.aries.samples.helloworld.blueprint.server project |
| shows |
| <br> |
| <br> |
| <img alt="hw3" src="HW3.png" /> |
| <br> |
| <br> |
| There are again two interesting files. HelloWorldServiceImpl.java is an |
| implementation of the HelloWorldService interface in the first |
| blueprint-helloworld-api project. The file config.xml is the Blueprint |
| configuration for this package. </p> |
| <p>The org.apache.aries.samples.helloworld.blueprint.client project looks like |
| this |
| <br> |
| <br> |
| <img alt="hw4" src="HW4.png" /> |
| <br> |
| <br> |
| The client implementation is in HelloWorldClient.java. The file config.xml |
| contains the Blueprint for the client.</p> |
| <p><a name="BlueprintHelloWorldTutorial-TheBlueprintXML"></a></p> |
| <h3 id="the-blueprint-xml">The Blueprint XML<a class="headerlink" href="#the-blueprint-xml" title="Permanent link">¶</a></h3> |
| <p>Blueprint xml files contain all the information that the Blueprint runtime |
| needs to internally wire a bundle's components. They also contain the |
| information that the Blueprint runtime needs to register and locate |
| services in the OSGi service registry. This allows for service-based |
| interactions between bundles. </p> |
| <p>This is a view of what the xml in the two config.xml files is describing: |
| <br> |
| <br> |
| <img alt="hw5" src="BPTutorial5F.png" /> |
| <br> |
| <br></p> |
| <p>The client configuration file has one bean definition which names the Java |
| class that it requires and gives the name of the method that will be run |
| when the bean has been initialised. The bean definition also describes a |
| property, helloWorldService, which points (see the arrow) to the reference |
| definition. This is telling Blueprint that the bean (helloclient) needs the |
| container to supply a service matched by the 'helloservice' reference, |
| which in turns specifies the interface to be implemented by that service. |
| <br> |
| <br> |
| <img alt="hw6" src="BPTutorial6F.png" /> |
| <br> |
| <br></p> |
| <p>The server configuration file is similar - with one bean definition which |
| points to the Java class that implements HelloWorldService. The second |
| element in this file is the service definition. This registers a service |
| under the HelloWorldService interface, implemented by the 'helloservice' |
| bean. |
| <br> |
| <br> |
| <img alt="hw7" src="BPTutorial7F.png" /> |
| <br> |
| <br></p> |
| <p><a name="BlueprintHelloWorldTutorial-TheJavaclasses"></a></p> |
| <h3 id="the-java-classes">The Java classes<a class="headerlink" href="#the-java-classes" title="Permanent link">¶</a></h3> |
| <p>Both the Java classes are very simple, there are just a couple of minor |
| points to make about each one. The HelloWorldClient class looks like |
| this: |
| <br> |
| <br> |
| <img alt="hw8" src="BPTutorial8F.png" /> |
| <br> |
| <br></p> |
| <ol> |
| <li>The setHelloWorldService() method will be called by the Blueprint |
| container in order to inject an object implementing the HelloWorldService |
| interface. </li> |
| <li>The startUp() method will be run when the bundle is started: remember |
| that this was specified in the Blueprint. This method executes a hello() |
| method which must be supplied by an implementation of HelloWorldService. |
| The startUp() method in this case will only be run after dependencies have |
| been injected. This is the default Blueprint behaviour.</li> |
| </ol> |
| <p>The HelloWorldServiceImpl class is even simpler. It has two |
| methods: |
| <br> |
| <br> |
| <img alt="hw9" src="BPTutorial9F.png" /> |
| <br> |
| <br></p> |
| <ol> |
| <li>A startUp() method which writes a message to say that the bundle is being |
| started </li> |
| <li>A hello() method which writes a 'hello' message</li> |
| </ol> |
| <p><a name="BlueprintHelloWorldTutorial-Runningthecode"></a></p> |
| <h3 id="running-the-code">Running the code<a class="headerlink" href="#running-the-code" title="Permanent link">¶</a></h3> |
| <p>The code can be run on an Equinox (or Felix) framework. The |
| org.apache.aries.samples.helloworld.blueprint.assembly package assembles an |
| Equinox based platform that contains all of the OSGi bundles you need. To |
| start it up go to the target directory in |
| org.apache.aries.samples.helloworld.blueprint.assembly, and from command |
| line, type:</p> |
| <div class="codehilite"><pre><span class="n">java</span> <span class="o">-</span><span class="n">jar</span> <span class="n">osgi</span><span class="o">-</span>3<span class="p">.</span>5<span class="p">.</span>0<span class="p">.</span><span class="n">v20090520</span><span class="p">.</span><span class="n">jar</span> <span class="o">-</span><span class="n">console</span> |
| </pre></div> |
| |
| |
| <p>You will see some messages, after which you should get the 'osgi>' prompt; |
| sometimes you will need to press return to see it. At the prompt, type 'ss' |
| to see the status of the bundles: |
| <br> |
| <br> |
| <img alt="hw10" src="BPTutorial10.png" /> |
| <br> |
| <br> |
| Next, start the Blueprint container bundle by typing 'start 5' at the osgi |
| prompt. You will see many debug messages in the code, this is because the |
| target/configuration/config.ini specifies the message level to be DEBUG, if |
| there are too many messages you can change this to 'INFO'. The debug |
| messages are quite interesting to look through in themselves, but a little |
| beyond the scope of this tutorial. The last debug message should indicate |
| that a Blueprint container is running in state 'created'. After that, start |
| the blueprint-helloworld-api in the same way by typing 'start 6' at the |
| prompt.</p> |
| <p>The next step is to start the blueprint-helloworld-server bundle. In |
| amongst the DEBUG messages you should see the single line of output from |
| the startUp() method if the HelloWorldServiceImpl class:</p> |
| <div class="codehilite"><pre><span class="o">======>>></span> <span class="n">Starting</span> <span class="n">HelloWorld</span> <span class="n">Server</span> |
| </pre></div> |
| |
| |
| <p>At this point it is possible to see if the HelloWorldService is registered, |
| like this:</p> |
| <div class="codehilite"><pre><span class="n">osgi</span><span class="o">></span> <span class="n">services</span> <span class="p">(</span><span class="n">objectClass</span><span class="p">=</span><span class="n">org</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">aries</span><span class="p">.</span><span class="n">samples</span><span class="p">.</span><span class="n">blueprint</span><span class="p">.</span><span class="n">helloworld</span><span class="p">.</span><span class="n">api</span><span class="p">.</span><span class="n">HelloWorldService</span><span class="p">)</span> |
| </pre></div> |
| |
| |
| <p>running this command will tell you that a service is registered but that |
| nothing is using it.</p> |
| <p>Finally, start the blueprint-helloworld-client bundle. If things have gone |
| according to plan you should see a sequence of 3 messages from the |
| startUp() method, the second message will be a 'hello' from |
| HelloWorldService:</p> |
| <div class="codehilite"><pre><span class="o">========>>>></span><span class="n">Client</span> <span class="n">HelloWorld</span><span class="p">:</span> <span class="n">About</span> <span class="n">to</span> <span class="n">execute</span> <span class="n">a</span> <span class="n">method</span> <span class="n">from</span> <span class="n">the</span> <span class="n">Hello</span> <span class="n">World</span> <span class="n">server</span> |
| <span class="o">======>>></span> <span class="n">A</span> <span class="n">message</span> <span class="n">from</span> <span class="n">the</span> <span class="n">server</span><span class="p">:</span> <span class="n">Hello</span> <span class="n">World</span>! |
| <span class="o">========>>>></span><span class="n">Client</span> <span class="n">HelloWorld</span><span class="p">:</span> <span class="p">...</span> <span class="k">if</span> <span class="n">you</span> <span class="n">didn</span><span class="o">'</span><span class="n">t</span> <span class="n">just</span> <span class="n">see</span> <span class="n">a</span> <span class="n">Hello</span> <span class="n">World</span> <span class="n">message</span> <span class="n">something</span> <span class="n">went</span> <span class="n">wrong</span> |
| </pre></div> |
| |
| |
| <p>If you re-run the services command above it will tell you that the |
| blueprint-helloworldclient bundle is using the blueprint-helloworldservice.</p> |
| <p>One interesting experiment is to start the blueprint-helloworldclient |
| bundle before the blueprint-helloworldserver bunde. When you do this, you |
| will see no output until the second bundle is started because the |
| 'helloclient' bean cannot be initialised until that point. If you wait more |
| than five minutes by default, there will be a timeout and the client will |
| not be initialised at all.</p> |
| <p><a name="BlueprintHelloWorldTutorial-Summary"></a></p> |
| <h3 id="summary">Summary<a class="headerlink" href="#summary" title="Permanent link">¶</a></h3> |
| <p>In the tutorial you have seen how to construct three simple Blueprint |
| bundles. The client bundle depends directly on the api and indirectly on |
| the server bundle. Blueprint takes care of registering a service from the |
| server bundle so that the client bundle can use it. You will have some |
| appreciation of the classes and XML that form a Blueprint application, and |
| you have seen a simple example working. Of course, this tutorial barely |
| touches on many of the features provided by the Aries Blueprint |
| implementation. Anyone keen to explore the features of Blueprint should |
| look at this <a href="http://www.ibm.com/developerworks/opensource/library/os-osgiblueprint/index.html">article</a> |
| and continue by reading the [OSGi specification|http://www.osgi.org/Download/Release4V42] |
| (see the 4.2 Compendium spec, section 121, "Blueprint Container |
| Specification") and making modifications to the sample code.</p></div> |
| <!-- Content --> |
| </td> |
| </tr> |
| </table> |
| </td> |
| <td id="cell-2-2" colspan="2"> </td> |
| </tr> |
| <tr width="100%"> |
| <td id="cell-3-0"> </td> |
| <td id="cell-3-1"> </td> |
| <td id="cell-3-2"> |
| <div id="footer"> |
| <!-- Footer --> |
| <div id="site-footer"> |
| <a href="http://aries.apache.org/privacy-policy.html";>Privacy |
| Policy</a> |
| </div> |
| <!-- Footer --> |
| </div> |
| </td> |
| <td id="cell-3-3"> </td> |
| <td id="cell-3-4"> </td> |
| </tr> |
| <tr width="100%"> |
| <td id="cell-4-0" colspan="2"> </td> |
| <td id="cell-4-1"> </td> |
| <td id="cell-4-2" colspan="2"> </td> |
| </tr> |
| </table> |
| </body> |
| </html> |
