| <!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 - Blueprint |
| </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/containers.html">Containers</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> |
| |
| <div class="promotion"> |
| <a href="http://www.apache.org/events/current-event.html"> |
| <img src="http://www.apache.org/events/current-event-125x125.png" width="125" height="125"/> |
| </a> |
| </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="Blueprint-Blueprint"></a></p> |
| <h1 id="blueprint">Blueprint<a class="headerlink" href="#blueprint" title="Permanent link">¶</a></h1> |
| <p><a name="Blueprint-Introduction"></a></p> |
| <h2 id="introduction">Introduction<a class="headerlink" href="#introduction" title="Permanent link">¶</a></h2> |
| <p>Blueprint provides a dependency injection framework for OSGi and was |
| standardized by the OSGi Alliance in OSGi Compendium R4.2. It is designed |
| to deal with the dynamic nature of OSGi, where services can become |
| available and unavailable at any time. The specification is also designed |
| to work with plain old Java objects (POJOs) enabling simple components to |
| be written and unit tested in a JSE environment without needing to be aware |
| of how they are assembled. The Blueprint XML files that define and describe |
| the assembly of various components are key to the Blueprint programming |
| model. The specification describes how the components get instantiated and |
| wired together to form a running module. </p> |
| <p>The following documentation covers the 80:20 usage of Blueprint. For |
| further details, please refer to the OSGi Compendium R4.2 specification.</p> |
| <p><a name="Blueprint-BlueprintBundles"></a></p> |
| <h2 id="blueprint-bundles">Blueprint Bundles<a class="headerlink" href="#blueprint-bundles" title="Permanent link">¶</a></h2> |
| <p>The Blueprint Container specification uses an extender pattern, whereby an |
| extender bundle monitors the state of bundles in the framework and performs |
| actions on behalf of those bundles based on their state. The Blueprint |
| extender bundle waits for the bundles to be activated and checks whether |
| they are Blueprint bundles. A bundle is considered to be a Blueprint bundle |
| when it contains one or more Blueprint XML files. These XML files are at a |
| fixed location under the OSGI-INF/blueprint/ directory or are specified |
| explicitly in the Bundle-Blueprint manifest header.</p> |
| <p>Once the extender determines that a bundle is a Blueprint bundle, it |
| creates a Blueprint Container on behalf of that bundle. The Blueprint |
| Container is responsible for:</p> |
| <ul> |
| <li>Parsing the Blueprint XML files</li> |
| <li>Instantiating the components</li> |
| <li>Wiring the components together</li> |
| <li>Registering services</li> |
| <li>Looking up service references</li> |
| </ul> |
| <p>During initialization, the Blueprint Container ensures that mandatory |
| service references are satisfied, registers all the services into the |
| service registry, and creates initial component instances. The Blueprint |
| extender bundle also destroys the Blueprint Container for a bundle when the |
| bundle is stopped. </p> |
| <p><a name="Blueprint-BlueprintXML"></a></p> |
| <h2 id="blueprint-xml">Blueprint XML<a class="headerlink" href="#blueprint-xml" title="Permanent link">¶</a></h2> |
| <p>The Blueprint XML file is identified by a top-level blueprint element, as |
| shown below:</p> |
| <div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> |
| <span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span><span class="nt">></span> |
| ... |
| <span class="nt"></blueprint></span> |
| </pre></div> |
| |
| |
| <p>The XML namespace identifies the document as conforming to the Blueprint |
| version 1.0.0. The top-level blueprint element identifies the document as |
| a blueprint module definition.</p> |
| <p><em>TODO:</em> ensure id, activation and dependsOn get documented somewhere.</p> |
| <p><a name="Blueprint-Beans"></a></p> |
| <h2 id="beans">Beans<a class="headerlink" href="#beans" title="Permanent link">¶</a></h2> |
| <p>Beans are declared using the bean element. The following defines a single |
| bean called <em>accountOne</em> implemented by the POJO |
| <em>org.apache.aries.simple.Account</em>.</p> |
| <div class="codehilite"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> |
| <span class="nt"><blueprint</span> <span class="na">xmlns=</span><span class="s">"http://www.osgi.org/xmlns/blueprint/v1.0.0"</span><span class="nt">></span> |
| <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountOne"</span> <span class="na">class=</span><span class="s">"org.apache.aries.simple.Account"</span> <span class="nt">/></span> |
| <span class="nt"></blueprint></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-BeanConstruction"></a></p> |
| <h3 id="bean-construction">Bean Construction<a class="headerlink" href="#bean-construction" title="Permanent link">¶</a></h3> |
| <p>During object construction, the Blueprint Container must first find the |
| right constructor or a factory method with a compatible set of parameters |
| that matches the arguments specified in the XML. By default, the Blueprint |
| Container uses the number and order of the argument elements in XML to find |
| the right constructor or method. If the argument elements cannot be mapped |
| to the parameters in the order they are in, the Blueprint Container will |
| attempt to reorder the argument elements and find the best-fitting |
| arrangement.</p> |
| <p>To help the Blueprint Container pick the right constructor, method, or |
| parameter arrangement, additional attributes, such as index or type, can be |
| specified on the argument element. For example, the type attribute |
| specifies a class name used to match the argument element to a parameter by |
| the exact type. </p> |
| <p>A bean can be constructed using a class constructor. In the following |
| example, the <em>class</em> attribute specifies the name of the Java class to |
| instantiate. The Blueprint Container will create the <em>Account</em> object by |
| passing <em>1</em> as the argument to the constructor. </p> |
| <div class="codehilite"><pre> :::java |
| public class Account { |
| public Account(long number) { |
| ... |
| } |
| ... |
| } |
| |
| |
| |
| <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountOne"</span> <span class="na">class=</span><span class="s">"org.apache.aries.simple.Account"</span><span class="nt">></span> |
| <span class="nt"><argument</span> <span class="na">value=</span><span class="s">"1"</span><span class="nt">/></span> |
| <span class="nt"></bean></span> |
| </pre></div> |
| |
| |
| <p>A bean can be constructed using a static factory method. In this example, |
| the <em>class</em> attribute specifies the name of the class that contains a |
| static factory method. The name of the static factory method is specified |
| by the <em>factory-method</em> attribute. The Blueprint Container will call the |
| <em>createAccount()</em> static method on the <em>StaticAccountFactory</em> class and |
| pass 2 as the argument to create the Account object. </p> |
| <div class="codehilite"><pre> public class StaticAccountFactory { |
| public static Account createAccount(long number) { |
| return new Account(number); |
| } |
| } |
| |
| |
| |
| <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountTwo"</span> |
| <span class="na">class=</span><span class="s">"org.apache.aries.simple.StaticAccountFactory"</span> |
| <span class="na">factory-method=</span><span class="s">"createAccount"</span><span class="nt">></span> |
| <span class="nt"><argument</span> <span class="na">value=</span><span class="s">"2"</span><span class="nt">/></span> |
| <span class="nt"></bean></span> |
| </pre></div> |
| |
| |
| <p>A bean can be constructed using an instance factory method. In the |
| example, the <em>accountFactory</em> bean is the factory. The Blueprint |
| Container will first create the <em>AccountFactory</em> instance with its own |
| arguments and properties. In this case, only a single argument is |
| specified: the factory name. The Blueprint Container will then call the |
| <em>createAccount()</em> method on the <em>AccountFactory</em> instance and pass 3 as |
| the argument to create the Account object.</p> |
| <p>public class AccountFactory { <br /> |
| public AccountFactory(String factoryName) { |
| ... |
| } |
| public Account createAccount(long number) { |
| return new Account(number); |
| } |
| }</p> |
| <div class="codehilite"><pre> <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountFactory"</span> |
| <span class="na">class=</span><span class="s">"org.apache.aries.simple.AccountFactory"</span><span class="nt">></span> |
| <span class="nt"><argument</span> <span class="na">value=</span><span class="s">"account factory"</span><span class="nt">/></span> |
| <span class="nt"></bean></span> |
| |
| <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountThree"</span> |
| <span class="na">factory-ref=</span><span class="s">"accountFactory"</span> |
| <span class="na">factory-method=</span><span class="s">"createAccount"</span><span class="nt">></span> |
| <span class="nt"><argument</span> <span class="na">value=</span><span class="s">"3"</span><span class="nt">/></span> |
| <span class="nt"></bean></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-BeanProperties"></a></p> |
| <h3 id="bean-properties">Bean Properties<a class="headerlink" href="#bean-properties" title="Permanent link">¶</a></h3> |
| <p>Beans can have property values injected. Injection is performed |
| immediately after the bean is constructed. The following example creates |
| the Account bean and then sets the description property using the Java |
| Beans naming convention.</p> |
| <p>public class Account { <br /> |
| public Account(long number) { |
| ... |
| } |
| public String getDescription() { |
| ... |
| } |
| }</p> |
| <div class="codehilite"><pre> <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountOne"</span> <span class="na">class=</span><span class="s">"org.apache.aries.simple.Account"</span><span class="nt">></span> |
| <span class="nt"><argument</span> <span class="na">value=</span><span class="s">"1"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"description"</span> <span class="na">value=</span><span class="s">"#1 account"</span><span class="nt">/></span> |
| <span class="nt"></bean></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-BeanWiring"></a></p> |
| <h4 id="bean-wiring">Bean Wiring<a class="headerlink" href="#bean-wiring" title="Permanent link">¶</a></h4> |
| <p>Property injection is used for wiring beans together. In the following |
| example <em>accountOne</em> is injected with a <em>Currency</em> bean.</p> |
| <div class="codehilite"><pre> public class Account { |
| public Account() { |
| ... |
| } |
| public void setCurrency(Currency currency) { |
| ... |
| } |
| } |
| |
| |
| |
| public class Currency { |
| public Currency() { |
| ... |
| } |
| } |
| |
| |
| |
| <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountOne"</span> <span class="na">class=</span><span class="s">"org.apache.aries.simple.Account"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"currency"</span> <span class="na">ref=</span><span class="s">"currency"</span> <span class="nt">/></span> |
| <span class="nt"></bean></span> |
| |
| <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"currency"</span> <span class="na">class=</span><span class="s">"org.apache.aries.simple.Currency"</span> <span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-Services"></a></p> |
| <h2 id="services">Services<a class="headerlink" href="#services" title="Permanent link">¶</a></h2> |
| <p>In Blueprint XML, a service element defines the registration of a service |
| in the OSGi service registry. </p> |
| <p>The bean that provides the service object can be referenced using the |
| <em>ref</em> attribute. The interfaces under which the service is registered |
| can be specified using the <em>interface</em> attribute:</p> |
| <div class="codehilite"><pre> <span class="n">public</span> <span class="n">class</span> <span class="n">AccountImpl</span> <span class="n">implements</span> <span class="n">Account</span> <span class="p">{</span> |
| <span class="n">public</span> <span class="n">Account</span><span class="p">()</span> <span class="p">{</span> |
| <span class="p">...</span> |
| <span class="p">}</span> |
| <span class="n">public</span> <span class="n">void</span> <span class="n">setCurrency</span><span class="p">(</span><span class="n">Currency</span> <span class="n">currency</span><span class="p">)</span> <span class="p">{</span> |
| <span class="p">...</span> |
| <span class="p">}</span> |
| <span class="p">}</span> |
| |
| |
| |
| <span class="o"><</span><span class="n">service</span> <span class="n">id</span><span class="p">=</span>"<span class="n">serviceOne</span>" <span class="n">ref</span><span class="p">=</span>"<span class="n">account</span>" |
| <span class="n">interface</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">simple</span><span class="p">.</span><span class="n">Account</span>" <span class="o">/></span> |
| |
| <span class="o"><</span><span class="n">bean</span> <span class="n">id</span><span class="p">=</span>"<span class="n">account</span>" <span class="n">class</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">simple</span><span class="p">.</span><span class="n">AccountImpl</span>" <span class="o">/></span> |
| </pre></div> |
| |
| |
| <p>The bean that provides the service object can be inlined in the service |
| element as follows:</p> |
| <div class="codehilite"><pre> <span class="nt"><service</span> <span class="na">id=</span><span class="s">"serviceTwo"</span> <span class="na">interface=</span><span class="s">"org.apache.aries.simple.Account"</span><span class="nt">></span> |
| <span class="nt"><bean</span> <span class="na">class=</span><span class="s">"org.apache.aries.simple.AccountImpl"</span> <span class="nt">/></span> |
| <span class="nt"></service></span> |
| </pre></div> |
| |
| |
| <p>The interfaces under which a service is registered can be determined by |
| Blueprint using <em>auto-export</em>. The following registers the service under |
| all the bean's interfaces:</p> |
| <div class="codehilite"><pre> <span class="o"><</span><span class="n">service</span> <span class="n">id</span><span class="p">=</span>"<span class="n">serviceOne</span>" <span class="n">ref</span><span class="p">=</span>"<span class="n">account</span>" <span class="n">auto</span><span class="o">-</span><span class="n">export</span><span class="p">=</span>"<span class="n">interfaces</span>" <span class="o">/></span> |
| |
| <span class="o"><</span><span class="n">bean</span> <span class="n">id</span><span class="p">=</span>"<span class="n">account</span>" <span class="n">class</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">simple</span><span class="p">.</span><span class="n">AccountImpl</span>" <span class="o">/></span> |
| </pre></div> |
| |
| |
| <p>Other values for <em>auto-export</em> are <em>disabled</em> (the default) |
| <em>class-hierarchy</em> and <em>all-classes</em>.</p> |
| <p><a name="Blueprint-ServiceProperties"></a></p> |
| <h3 id="service-properties">Service Properties<a class="headerlink" href="#service-properties" title="Permanent link">¶</a></h3> |
| <p>A service can also be registered with a set of properties that can be |
| specified using the <em>service-properties</em> sub-element. The |
| <em>service-properties</em> element contains multiple <em>entry</em> sub-elements |
| that represent the individual properties. The property key is specified |
| using a <em>key</em> attribute, but the property value can be specified as a |
| <em>value</em> attribute or inlined within the element. The service property |
| values can be of different types, but only OSGi service property types are |
| permitted: primitives, primitive wrapper classes, collections, or arrays of |
| primitive types. </p> |
| <p>The following is an example of a service registration with two service |
| properties. The <em>active</em> service property has type of |
| <em>java.lang.Boolean</em>. The <em>mode</em> property is of the default type, |
| <em>String</em>. </p> |
| <div class="codehilite"><pre> <span class="nt"><service</span> <span class="na">id=</span><span class="s">"serviceFour"</span> <span class="na">ref=</span><span class="s">"account"</span> <span class="na">autoExport=</span><span class="s">"all-classes"</span><span class="nt">></span> |
| <span class="nt"><service-properties></span> |
| <span class="nt"><entry</span> <span class="na">key=</span><span class="s">"active"</span><span class="nt">></span> |
| <span class="nt"><value</span> <span class="na">type=</span><span class="s">"java.lang.Boolean"</span><span class="nt">></span>true<span class="nt"></value></span> |
| <span class="nt"></entry></span> |
| <span class="nt"><entry</span> <span class="na">key=</span><span class="s">"mode"</span> <span class="na">value=</span><span class="s">"shared"</span><span class="nt">/></span> |
| <span class="nt"></service-properties></span> |
| <span class="nt"></service></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-ServiceRanking"></a></p> |
| <h3 id="service-ranking">Service Ranking<a class="headerlink" href="#service-ranking" title="Permanent link">¶</a></h3> |
| <p>Service ranking can be used to affect the choice of service when there are |
| multiple matches. When choosing between two services, the higher ranked |
| service will be returned ahead of the lower. The default ranking value is |
| 0. Service ranking is specified using the <em>ranking</em> attributes as |
| follows:</p> |
| <div class="codehilite"><pre> <span class="o"><</span><span class="n">service</span> <span class="n">id</span><span class="p">=</span>"<span class="n">serviceFive</span>" <span class="n">ref</span><span class="p">=</span>"<span class="n">account</span>" <span class="n">auto</span><span class="o">-</span><span class="n">export</span><span class="p">=</span>"<span class="n">all</span><span class="o">-</span><span class="n">classes</span>" |
| <span class="n">ranking</span><span class="p">=</span>"3" <span class="o">/></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-References"></a></p> |
| <h2 id="references">References<a class="headerlink" href="#references" title="Permanent link">¶</a></h2> |
| <p>Services are found in the service registry using the reference element. The |
| following shows a reference named <em>accountRef</em> to an <em>Account</em> service. |
| If a service matching this reference is found in the service registry then |
| it is set on the <em>accountClient</em> bean through the <em>account</em> property.</p> |
| <div class="codehilite"><pre> <span class="nt"><bean</span> <span class="na">id=</span><span class="s">"accountClient"</span> <span class="na">class=</span><span class="s">"..."</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"account"</span> <span class="na">ref=</span><span class="s">"accountRef"</span> <span class="nt">/></span> |
| <span class="nt"></bean></span> |
| |
| <span class="nt"><reference</span> <span class="na">id=</span><span class="s">"accountRef"</span> <span class="na">interface=</span><span class="s">"org.apache.aries.simple.Account"</span> |
| <span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p><a name="Blueprint-ReferenceDynamism"></a></p> |
| <h3 id="reference-dynamism">Reference Dynamism<a class="headerlink" href="#reference-dynamism" title="Permanent link">¶</a></h3> |
| <p>The object that is injected for a reference is actually a proxy to the |
| service registered in the service registry. A proxy enables the injected |
| object to remain the same while the backing service can come and go or be |
| replaced with another service. Calls on a proxy that does not have a |
| backing service will block until a service becomes available or a timeout |
| occurs at which point a ServiceUnavailableException will be thrown.</p> |
| <div class="codehilite"><pre> <span class="k">try</span> <span class="p">{</span> |
| <span class="n">balance</span> <span class="p">=</span> <span class="n">account</span><span class="p">.</span><span class="n">getBalance</span><span class="p">();</span> |
| <span class="p">}</span> <span class="k">catch</span> <span class="p">(</span><span class="n">ServiceUnavailableException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span> |
| <span class="p">...</span> |
| <span class="p">}</span> |
| </pre></div> |
| |
| |
| <p>The default timeout Blueprint will wait for is 300000 milliseconds (5 |
| minutes). This value can be changed on a per bundle basis using directives |
| on the Bundle-SymbolicName. The following switches the timeout off |
| completely (the default is true):</p> |
| <div class="codehilite"><pre> <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</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">simple</span><span class="p">.</span><span class="n">account</span><span class="p">;</span> |
| <span class="n">blueprint</span><span class="p">.</span><span class="n">graceperiod</span><span class="p">:=</span><span class="n">false</span> |
| </pre></div> |
| |
| |
| <p>The following sets the timeout to 10000 milliseconds (10 seconds):</p> |
| <div class="codehilite"><pre> <span class="n">Bundle</span><span class="o">-</span><span class="n">SymbolicName</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">simple</span><span class="p">.</span><span class="n">account</span><span class="p">;</span> |
| <span class="n">blueprint</span><span class="p">.</span><span class="n">graceperiod</span><span class="p">:=</span><span class="n">false</span><span class="p">;</span> <span class="n">blueprint</span><span class="p">.</span><span class="n">timeout</span><span class="p">=</span>10000<span class="p">;</span> |
| </pre></div> |
| |
| |
| <p>The timeout can also be set on an individual reference using the |
| <em>timeout</em> attribute. The following sets the timeout for the account |
| reference to 20000 milliseconds (20 seconds).</p> |
| <div class="codehilite"><pre> <span class="o"><</span><span class="n">reference</span> <span class="n">id</span><span class="p">=</span>"<span class="n">accountRef</span>" <span class="n">timeout</span><span class="p">=</span>"20000" |
| <span class="n">interface</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">simple</span><span class="p">.</span><span class="n">Account</span>" <span class="o">/></span> |
| </pre></div> |
| |
| |
| <p>In all cases, a value of 0 means wait indefinitely for the reference to |
| become satisfied.</p> |
| <p><a name="Blueprint-ReferenceLists"></a></p> |
| <h3 id="reference-lists">Reference Lists<a class="headerlink" href="#reference-lists" title="Permanent link">¶</a></h3> |
| <p>Multiple matching services can be found using the <em>reference-list</em> |
| element. The <em>reference-list</em> provides a <em>List</em> object that contains |
| the service proxy objects or <em>ServiceReference</em> objects, depending on the |
| <em>member-type</em> setting. The provided <em>List</em> object is dynamic, as it can |
| grow and shrink as matching services are added or removed from the service |
| registry. The <em>List</em> object is read-only and only supports a subset of |
| the <em>List</em> API.</p> |
| <p>The proxies in a <em>reference-list</em> are different from the proxies for a |
| reference. The <em>reference-list</em> proxies target a specific service, do not |
| have a <em>timeout</em>, and throw <em>ServiceUnavailableException</em> immediately |
| if their service becomes unavailable.</p> |
| <p>The following example shows a reference-list that returns a list of service |
| objects (proxies). This is the default value for the <em>member-type</em> |
| attribute</p> |
| <div class="codehilite"><pre> <span class="o"><</span><span class="n">reference</span><span class="o">-</span><span class="n">list</span> <span class="n">id</span><span class="p">=</span>"<span class="n">accountRefs</span>" <span class="n">member</span><span class="o">-</span><span class="n">type</span><span class="p">=</span>"<span class="n">service</span><span class="o">-</span><span class="n">object</span>" |
| <span class="n">interface</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">simple</span><span class="p">.</span><span class="n">Account</span>" <span class="o">/></span> |
| </pre></div> |
| |
| |
| <p>The following shows an example of a reference-list that returns a list of |
| ServiceReferences:</p> |
| <div class="codehilite"><pre> <span class="o"><</span><span class="n">reference</span><span class="o">-</span><span class="n">list</span> <span class="n">id</span><span class="p">=</span>"<span class="n">accountRefs</span>" <span class="n">member</span><span class="o">-</span><span class="n">type</span><span class="p">=</span>"<span class="n">service</span><span class="o">-</span><span class="n">reference</span>" |
| <span class="n">interface</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">simple</span><span class="p">.</span><span class="n">Account</span>" <span class="o">/></span> |
| </pre></div> |
| |
| |
| <p>Example showing mandatory or optional references (availability)</p> |
| <p>Example showing use of filter</p> |
| <p><a name="Blueprint-BeanProperties"></a></p> |
| <h2 id="bean-properties_1">Bean Properties<a class="headerlink" href="#bean-properties_1" title="Permanent link">¶</a></h2> |
| <p>Example showing use of bean properties</p> |
| <p><a name="Blueprint-Scopes"></a></p> |
| <h2 id="scopes">Scopes<a class="headerlink" href="#scopes" title="Permanent link">¶</a></h2> |
| <p>Example showing singleton scope</p> |
| <p>Example showing prototype scope for beans</p> |
| <p>Example showing prototype scope for services</p> |
| <p><a name="Blueprint-ObjectValues"></a></p> |
| <h2 id="object-values">Object Values<a class="headerlink" href="#object-values" title="Permanent link">¶</a></h2> |
| <p>Intro to Object Values</p> |
| <p>Examples showing the use of the various different object value types - ref, |
| map, props collection (list, array, set).</p> |
| <p><a name="Blueprint-Lifecycle"></a></p> |
| <h2 id="lifecycle">Lifecycle<a class="headerlink" href="#lifecycle" title="Permanent link">¶</a></h2> |
| <p>Example showing use of init/destroy-method</p> |
| <p><a name="Blueprint-LazyandEagerActiviation"></a></p> |
| <h2 id="lazy-and-eager-activiation">Lazy and Eager Activiation<a class="headerlink" href="#lazy-and-eager-activiation" title="Permanent link">¶</a></h2> |
| <p>Example showing lazy activiation.</p> |
| <p>Example showing eager activation.</p> |
| <p><a name="Blueprint-Dynamism"></a></p> |
| <h2 id="dynamism">Dynamism<a class="headerlink" href="#dynamism" title="Permanent link">¶</a></h2> |
| <p>Example showing service-listener</p> |
| <p>Example showing reference-listener</p> |
| <p><a name="Blueprint-TypeConverters"></a></p> |
| <h2 id="type-converters">Type Converters<a class="headerlink" href="#type-converters" title="Permanent link">¶</a></h2></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> |
