cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF > Distributed OSGi Reference
Date Thu, 27 Aug 2009 17:12:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/11/_/styles/combined.css?spaceKey=CXF&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/CXF/Distributed+OSGi+Reference">Distributed
OSGi Reference</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~sergey_beryozkin">Sergey
Beryozkin</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="DistributedOSGiReference-DistributedOSGiReferenceGuide"></a>Distributed
OSGi Reference Guide</h1>

<div>
<ul>
    <li><a href='#DistributedOSGiReference-DistributedOSGiReferenceGuide'>Distributed
OSGi Reference Guide</a></li>
<ul>
    <li><a href='#DistributedOSGiReference-ConfigurationProperties'>Configuration
Properties</a></li>
<ul>
    <li><a href='#DistributedOSGiReference-ServiceProviderpropertiesForConfiguringSOAPbasedservicesandconsumers'>Service
Provider properties For Configuring SOAP-based services and consumers</a></li>
    <li><a href='#DistributedOSGiReference-ServiceProviderpropertiesForConfiguringRESTfulJAXRSbasedendpointsandconsumers'>Service
Provider properties For Configuring RESTful JAXRS-based endpoints and consumers</a></li>
    <li><a href='#DistributedOSGiReference-ServiceConsumerproperties'>Service
Consumer properties</a></li>
</ul>
    <li><a href='#DistributedOSGiReference-TheIntentMap'>The Intent Map</a></li>
    <li><a href='#DistributedOSGiReference-%7B%7Bremoteservices.xml%7D%7Dfiles'>
<tt>remote-services.xml</tt> files</a></li>
    <li><a href='#DistributedOSGiReference-ContributingDistributionpropertiestoExistingServices%28withoutchangingthem%29'>Contributing
Distribution properties to Existing Services (without changing them)</a></li>
</ul>
</ul></div>

<h2><a name="DistributedOSGiReference-ConfigurationProperties"></a>Configuration
Properties</h2>

<p>These properties are set on the Service Registration in the OSGi Service Registry.</p>

<h3><a name="DistributedOSGiReference-ServiceProviderpropertiesForConfiguringSOAPbasedservicesandconsumers"></a>Service
Provider properties For Configuring SOAP-based services and consumers</h3>

<p><b>Note:</b> for backwards compatibility old values marked below are
still supported. </p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property Name </th>
<th class='confluenceTh'> Data Type </th>
<th class='confluenceTh'> Example </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> service.exported.interfaces<br/>
 (previously:<em>osgi.remote.interfaces</em>) </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt>org.example.BarService,org.example.FooService</tt>
<tt>*</tt></td>
<td class='confluenceTd'> Denotes the interfaces to be exposed remotely. This is a comma-separated
list of fully qualified Java interfaces that should be made available remotely. A special
value of <tt>*</tt> can be provided meaning that <em>all</em> of the
interfaces passed to the <tt>BundleContext.registerService()</tt> call are suitable
for remoting. </td>
</tr>
<tr>
<td class='confluenceTd'> service.exported.configs (previously:<em>osgi.remote.configuration.type</em>)
</td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt>org.apache.cxf.ws</tt> </td>
<td class='confluenceTd'> Specifies the mechanism for configuring the service exposure.
Possible values: 
<ul>
	<li><tt>org.apache.cxf.ws</tt> (previously: <tt>pojo</tt>)
the OSGi Service is exposed as a Web Service.</li>
	<li><tt>wsdl</tt> configuration driven from WSDL</li>
</ul>
</td>
</tr>
</tbody></table>

<h4><a name="DistributedOSGiReference-%7B%7Borg.apache.cxf.ws%7D%7Dconfigurationtype"></a><tt>org.apache.cxf.ws</tt>
configuration type</h4>
<p>When the <tt>service.exported.configs=org.apache.cxf.ws</tt> (or <tt>osgi.remote.configuration.type=pojo</tt>)
property is specified, the following properties may also be specified.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property Name </th>
<th class='confluenceTh'> Data Type </th>
<th class='confluenceTh'> Example </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.address<br/>
(previously:<em>osgi.remote.configuration.pojo.address</em>) </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt><a href="http://localhost:9090/greeter" rel="nofollow">http://localhost:9090/greeter</a></tt>
</td>
<td class='confluenceTd'> The address at which the service with be made available remotely.
If this property is not specified, this defaults to <tt><a href="http://localhost:9000/fully/qualified/ClassName"
rel="nofollow">http://localhost:9000/fully/qualified/ClassName</a></tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.ws.httpservice.context<br/>
(previously:<em>osgi.remote.configuration.pojo.httpservice.context</em>) </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt>/auction</tt> </td>
<td class='confluenceTd'> When this property is specified, the OSGi HTTP Service is
used to expose the service, rather than a dedicated Jetty HTTP Server. This property doesn't
allow the specification of a port number, as this is provided by the HTTP Service. The Distributed
OSGi distributions come with Pax-Web, for which configuration information can be found here:
<a href="http://wiki.ops4j.org/display/paxweb/Configuration" rel="nofollow">http://wiki.ops4j.org/display/paxweb/Configuration</a>,
however other OSGi HTTP Service implementations are potentially configured differently. </td>
</tr>
</tbody></table>

<h3><a name="DistributedOSGiReference-ServiceProviderpropertiesForConfiguringRESTfulJAXRSbasedendpointsandconsumers"></a>Service
Provider properties For Configuring RESTful JAXRS-based endpoints and consumers</h3>

<h4><a name="DistributedOSGiReference-%7B%7Borg.apache.cxf.rs%7D%7Dconfigurationtype"></a><tt>org.apache.cxf.rs</tt>
configuration type</h4>

<p>When the <tt>service.exported.configs=org.apache.cxf.rs</tt> property
is specified, the following properties may also be specified.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property Name </th>
<th class='confluenceTh'> Data Type </th>
<th class='confluenceTh'> Example </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.rs.address </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt><a href="http://localhost:9090/greeter" rel="nofollow">http://localhost:9090/greeter</a></tt>
</td>
<td class='confluenceTd'> The address at which the service with be made available remotely.
If this property is not specified, this defaults to <tt><a href="http://localhost:9000/fully/qualified/ClassName"
rel="nofollow">http://localhost:9000/fully/qualified/ClassName</a></tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.rs.httpservice.context </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt>/auction</tt> </td>
<td class='confluenceTd'> When this property is specified, the OSGi HTTP Service which
is used to expose the service, rather than a dedicated Jetty HTTP Server. By default, absolute
address may look like 'http://localhost:8080/auction'  </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.rs.provider </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> <tt>true} or {false</tt> </td>
<td class='confluenceTd'> Can be used to identify a global JAXRS provider as CXF-compatible
</td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.rs.provider.expected </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> <tt>true} or {false</tt> </td>
<td class='confluenceTd'> Can be used to require global providers to set an 'org.apache.cxf.rs.provider'
property with a value 'true'. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.rs.provider.globalquery </td>
<td class='confluenceTd'> Boolean </td>
<td class='confluenceTd'> <tt>true} or {false</tt> </td>
<td class='confluenceTd'> Can be used to disable queries for global providers, defaults
to 'true'. </td>
</tr>
</tbody></table>

<h4><a name="DistributedOSGiReference-RegisteringcustomJAXRSproviders"></a>Registering
custom JAXRS providers </h4>

<p>Custom JAXRS providers including CXF-specific providers can be registered like regular
OSGI services, for example :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-object">Object</span> provider = <span class="code-keyword">new</span>
CustomMessageBodyReaderWriter();
bundleContext.registerService(
  <span class="code-keyword">new</span> <span class="code-object">String</span>[]{<span
class="code-quote">"javax.ws.rs.ext.MessageBodyReader"</span>, <span class="code-quote">"javax.ws.rs.ext.MessageBodyReader"</span>},
provider);
</pre>
</div></div>

<p>Note that when registering a global provider, one may set an 'org.apache.cxf.rs.provider.expected'
on a given service description thus requiring providers to confirm that they will reliably
work with CXF JAX-RS by setting a 'org.apache.cxf.rs.provider' true property during the registration
- this may be needed when multiple JAX-RS implementations are available and some custom providers
depending on JAXRS implementation specific code.</p>

<p>Alternatively, one can register per-service specific providers during the application
service registration :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
CustomMessageBodyReaderWriter provider1 = <span class="code-keyword">new</span>
CustomMessageBodyReaderWriter();
provider.setCustomProperty(<span class="code-keyword">true</span>);
CustomMessageBodyReaderWriter provider2 = <span class="code-keyword">new</span>
CustomMessageBodyReaderWriter();
provider2.setCustomProperty(<span class="code-keyword">false</span>);

Dictionary properties = <span class="code-keyword">new</span> Hashtable();
properties.put(<span class="code-quote">"org.apache.cxf.rs.provider"</span>, provider);

Dictionary properties2 = <span class="code-keyword">new</span> Hashtable();
properties.put(<span class="code-quote">"org.apache.cxf.rs.provider"</span>, provider2);


bundleContext.registerService(
  <span class="code-keyword">new</span> <span class="code-object">String</span>[]{<span
class="code-quote">"org.books.BookService"</span>}, <span class="code-keyword">new</span>
BookServiceImpl(), properties);
bundleContext.registerService(
  <span class="code-keyword">new</span> <span class="code-object">String</span>[]{<span
class="code-quote">"org.books.BookService"</span>}, <span class="code-keyword">new</span>
AdvancedBookServiceImpl(), properties2);
</pre>
</div></div>


<h3><a name="DistributedOSGiReference-ServiceConsumerproperties"></a>Service
Consumer properties</h3>

<p>On client side proxies, typically the same properties are set as on set service provider
side for both SOAP and RESTful clients. There are some additional properties too. Since the
client-side proxy is registered by the DOSGi implementation, all these properties are read-only.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property Name </th>
<th class='confluenceTh'> Data Type </th>
<th class='confluenceTh'> Example </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> service.imported </td>
<td class='confluenceTd'> boolean </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> This property is always set on a service proxy, indicating
that the real service is remote. </td>
</tr>
<tr>
<td class='confluenceTd'> org.apache.cxf.remote.dsw.client </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'>&nbsp;</td>
<td class='confluenceTd'> This property is set to the bundle name of the CXF-DOSGi implementation
and can be used to find client side proxies created by the CXF DOSGi implementation. </td>
</tr>
</tbody></table>

<h2><a name="DistributedOSGiReference-TheIntentMap"></a>The Intent Map</h2>
<p><em><b>TODO</b></em></p>

<h2><a name="DistributedOSGiReference-%7B%7Bremoteservices.xml%7D%7Dfiles"></a><tt>remote-services.xml</tt>
files</h2>
<p>The CXF DOSGi implementation provides a DSW (Distribution Software) implementation
of Distributed OSGi. It is compatible with any Distributed OSGi Discovery implementation in
order to discover remote services dynamically. </p>

<p>However, using a Discovery system is optional, it is also possible to statically
configure remote services into the system. This is done by registering one or more bundles
containing <tt>remote-services.xml</tt> files. By default the system looks for
any files with the <tt>.xml</tt> extension in the <tt>OSGI-INF/remote-service</tt>
directory of the bundle.</p>

<p>Here's an example:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre> 
&lt;service-descriptions xmlns="http://www.osgi.org/xmlns/sd/v1.0.0"&gt;
  &lt;service-description&gt;
    &lt;provide interface="org.apache.cxf.dosgi.samples.greeter.GreeterService" /&gt;
    &lt;property name="osgi.remote.interfaces"&gt;*&lt;/property&gt;
    &lt;property name="osgi.remote.configuration.type"&gt;pojo&lt;/property&gt;
    &lt;property name="osgi.remote.configuration.pojo.address"&gt;http://localhost:9090/greeter&lt;/property&gt;
  &lt;/service-description&gt;

  &lt;!-- further service-description tags are allowed here --&gt;
&lt;/service-descriptions&gt;
</pre>
</div></div> 

<p><b>Alternative locations</b></p>

<p>By default all <tt>*.xml</tt> files in the OSGI-INF/remote-service location
are considered, this location can be changed by setting the <tt>Remote-Service</tt>
header in the bundle manifest, e.g.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>Remote-Service: META-INF/osgi</pre>
</div></div>

<h2><a name="DistributedOSGiReference-ContributingDistributionpropertiestoExistingServices%28withoutchangingthem%29"></a>Contributing
Distribution properties to Existing Services (without changing them)</h2>
<p>CXF/DOSGi allows you to add the distribution properties to existing OSGi services.
You can do this by installing a bundle that contains an XML file with the extra properties
in the <tt>OSGI-INF/remote-service</tt> directory:</p>

<p>A sample <tt>OSGI-INF/remote-service/sd.xml</tt> file looks like this:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>&lt;service-decorations xmlns="http://cxf.apache.org/xmlns/service-decoration/1.0.0"&gt;
 &lt;service-decoration&gt;
   &lt;match interface="org.apache.F(.*)"&gt;
     &lt;match-property name="test.prop" value="xyz"/&gt;
     &lt;add-property name="service.exported.interfaces" value="*"/&gt;
   &lt;/match&gt;
 &lt;/service-decoration&gt;
&lt;/service-decorations&gt;
</pre>
</div></div>
<p>A service decorations file can have any number of <tt>service-decoration</tt>
tags, each tag describing a <b>match</b> rule for services that are to be decorated.<br/>
The match rules are defined as follows:</p>
<ul>
	<li><tt>match interface="org.apache.Foo"</tt> matches any service that
is registered under the <em>org.apache.Foo</em> class or interface. The <tt>interface</tt>
attribute takes regular expressions, so specifying <tt>org.apache(.)*</tt> will
match any service registered with an interface in a subpackage of <em>org.apache</em>.</li>
	<li>The optional <tt>match-property</tt> tags allows you to declare extra
conditions to be applied to services of which the interface matches. In the above example
the rule will only match services that have the <tt>test.prop</tt> property set
to the value <tt>xyz</tt>. Other services don't match. Any number of <tt>match-property</tt>
tags can be specified.</li>
	<li>The <tt>add-property</tt> specifies the extra property to be added
to the remote service. The above example adds <tt>service.exported.interfaces="*"</tt>
which will cause any matching service to be exposed remotely. The <tt>add-property</tt>
has an optional <tt>type</tt> attribute which defaults to <tt>java.lang.String</tt>.
You can specify other Java basic types such as <tt>java.lang.Long</tt> if needed.
You can have any number of <tt>add-property</tt> tags.</li>
</ul>


<p>Note the bundle with the extra metadata will need to be started before the bundle
with the service that is to be remoted is started (need to fix this).</p>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/CXF/Distributed+OSGi+Reference">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=114450&revisedVersion=15&originalVersion=14">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/CXF/Distributed+OSGi+Reference?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message