cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > Multiplexed EndpointReferences
Date Tue, 29 Jan 2013 14:43:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/Multiplexed+EndpointReferences">Multiplexed
EndpointReferences</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~coheigea@apache.org">Colm
O hEigeartaigh</a>
    </h4>
        <br/>
                         <h4>Changes (3)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >   return EndpointReferenceUtils.getEndpointReferenceWithId(SERVICE_QNAME,
 <br>              portName, state, BusFactory.getDefaultBus());  <br></td></tr>
            <tr><td class="diff-unchanged" >} <br></td></tr>
            <tr><td class="diff-unchanged" >{noformat}  <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>{noformat}  <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">
</span> <span class="diff-added-words"style="background-color: #dfd;">@Resource</span>
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">
   @Resource <br></td></tr>
            <tr><td class="diff-unchanged" >protected WebServiceContext wsContext;
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-unchanged" >public boolean isEven() { <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-unchanged" >    MessageContext messageContext
= wsContext.getMessageContext();
    String state = EndpointReferenceUtils
        .getCurrentEndpointReferenceId(messageContext); <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-unchanged" >    int val = Integer.parseInt(state);
    return valIsEven(val);
} <br></td></tr>
            <tr><td class="diff-unchanged" >{noformat}  <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >The _multiplexWithAddress_ property
for HTTP is enabled by adding the following to cxf.xml <br>{noformat} <br></td></tr>
            <tr><td class="diff-unchanged" >&lt;bean name=&quot;&lt;port
name&gt;.http-destination&quot; abstract=&quot;true&quot;&gt;
  &lt;property name=&quot;multiplexWithAddress&quot; value=&quot;true&quot;/&gt;
&lt;/bean&gt; <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-unchanged" >&lt;!-- or for all http ports
(using a wildcard) --&gt;
&lt;bean name=&quot;*&quot; abstract=&quot;true&quot; class=&quot;org.apache.cxf.transport.http_jetty.JettyHTTPDestination&quot;&gt;
  &lt;property name=&quot;multiplexWithAddress&quot; value=&quot;true&quot;/&gt;
&lt;/bean&gt; <br></td></tr>
            <tr><td class="diff-unchanged" >{noformat}  <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Sample JAX-WS client code would do
the following to access a Number instance using an EPR -  <br>{noformat}  <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">
<br></td></tr>
            <tr><td class="diff-unchanged" >NumberFactoryService service = new
NumberFactoryService();
NumberFactory factory = service.getNumberFactoryPort(); <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-unchanged" >EndpointReferenceType epr = factory.create(&quot;20&quot;);
NumberService numService = new NumberService();
ServiceImpl serviceImpl = ServiceDelegateAccessor.get(numService);                   
Number num = (Number)serviceImpl.getPort(epr, Number.class);
... <br></td></tr>
            <tr><td class="diff-unchanged" >{noformat}  <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>Support for Multiplexed EndpointReferences in CXF allows a single stateless
service instance to represent/impersonate multiple service instances. The single service does
not maintain any state itself, but instead uses attributes of the current target EndpointReference
to identify instance data. The piggybacking of state in an EndpointReference is a form of
application level multiplexing. </p>

<p>To illustrate, consider a simple web service called <em>Number</em> that
represents an integer and supports a single operation <em>isEven</em> that returns
true iff the <em>Number</em> is even. Consider also a <em>NumberFactory</em>
service that returns Endpoint References(EPRs) to <em>Numbers</em> through an
operation <em>create(int)</em>. </p>

<p>A typical implementation of NumberFactory.create() would instantiate and publish
an endpoint for each requested integer value, returning the corresponding EPR to the caller.
Given the infinite set of possible <em>Number</em> values, this implementation
would scale poorly as the number of calls to create different values increase. </p>

<p>Enter multiplexed endpoint references. The implementation of NumberFactory.create()
instantiates and publishes a single template service. Then for each unique value of Number,
the implementation generates (using a CXF API) a multiplexed EPR for that particular value.
This EPR is returned to the caller. </p>

<p>The implementation of the single template Number service needs a mechanism to dynamically
determine its current state or value at runtime. It gets this from CXF based on the target
EndpointReference. It then proceeds to determine if the current value is even and returns
the result to the caller. </p>

<p>In this way, a single service instance can represent all possible Numbers, the only
state is embedded in the multiplexed endpoint references that are maintained by the callers.
</p>

<p>Here is skeleton implementation of NumberFactory.create():</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>EndpointReferenceType create(int val) {
   synchronized (this) {
     if (!servicePublished) {
        publishSingleInstanceServant(SERVICE_QNAME);
        servicePublished = true;
     }
   }
   String state = String.valueOf(val);
   String portName = null; // unless there are multiple ports in the service 
   return EndpointReferenceUtils.getEndpointReferenceWithId(SERVICE_QNAME, 
              portName, state, BusFactory.getDefaultBus()); 
}
</pre>
</div></div> 

<p>Here is the skeleton implementation of Number.isEven():</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre> 
@Resource
protected WebServiceContext wsContext;
    
public boolean isEven() {

    MessageContext messageContext = wsContext.getMessageContext();
    String state = EndpointReferenceUtils
        .getCurrentEndpointReferenceId(messageContext);
        
    int val = Integer.parseInt(state);
    return valIsEven(val);
}
</pre>
</div></div> 

<h5><a name="MultiplexedEndpointReferences-HowdoesitWork"></a>How does it
Work</h5>
<p>The API uses WS-Addressing(WS-A) reference parameters to embed the users state in
an EndpointReference. The reference parameters are part of the EPR that is returned to the
caller. WS-A interceptors are used to propagate the reference parameters as a soap header
on subsequent invocations using the returned EPR. On the receiving side, the current WS-A
MEPs are queried to extract the state from the reference parameters. </p>


<h5><a name="MultiplexedEndpointReferences-WorkingwithoutWSAddressing"></a>Working
without WS-Addressing</h5>
<p>WS-A provides a transport/protocol neutral approach to state transfer and is the
default mechanism for multiplexing supported by CXF. However some transports, notably HTTP,
have implicit support for multiplexing in the form of contexts and query parameters. The CXF
HTTP transport supports a <em>multiplexWithAddress</em> configuration attribute
that when enabled, negates the use of WS-A and forces the state to be embedded in the URL
context.</p>

<p>For example, in the Number scenario above, the single Number service endpoint would
publish a URL of the form: <a href="http://host:port/NumberService/Number/" class="external-link"
rel="nofollow">http://host:port/NumberService/Number/</a>  with a URL matching strategy
of stem. A call to NumberFactory.create(22) would result in an EPR that contained the address
element <a href="http://localhost:9080/NumberService/Number/22" class="external-link" rel="nofollow">http://localhost:9080/NumberService/Number/22</a>.
In this way, the multiplex state becomes a natural part of the HTTP endpoint address URL which
can be consumed by native HTTP clients. </p>

<p>The <em>multiplexWithAddress</em> property for HTTP is enabled by adding
the following to cxf.xml</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>&lt;bean name="&lt;port name&gt;.http-destination" abstract="true"&gt;
  &lt;property name="multiplexWithAddress" value="true"/&gt;
&lt;/bean&gt;

&lt;!-- or for all http ports (using a wildcard) --&gt;
&lt;bean name="*" abstract="true" class="org.apache.cxf.transport.http_jetty.JettyHTTPDestination"&gt;
  &lt;property name="multiplexWithAddress" value="true"/&gt;
&lt;/bean&gt;
</pre>
</div></div> 


<h5><a name="MultiplexedEndpointReferences-UsingEndpointRefernceswithaJAXWSService"></a>Using
EndpointRefernces with a JAX-WS Service</h5>
<p>JAX-WS 2.0 provides APIs that allow a port to be created with an EPR. CXF is working
towards JAX-WS 1.0 certification which is incompatible with JAX-WS 2.0. Thus in the short
term, CXF will not expose the useful JAX-WS 2.0 API. As an interim solution, CXF provides
a utility class <em>ServiceDelegateAccessor</em> that allows a JAX-WS client to
reference the underlying provider implementation object on which a getPort(EndpointReferenceType
..) method exists. </p>

<p>Sample JAX-WS client code would do the following to access a Number instance using
an EPR - </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre> 
NumberFactoryService service = new NumberFactoryService();
NumberFactory factory = service.getNumberFactoryPort();
        
EndpointReferenceType epr = factory.create("20");
NumberService numService = new NumberService();
ServiceImpl serviceImpl = ServiceDelegateAccessor.get(numService);                   
Number num = (Number)serviceImpl.getPort(epr, Number.class);
...
</pre>
</div></div> 
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/Multiplexed+EndpointReferences">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=52211&revisedVersion=5&originalVersion=4">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/Multiplexed+EndpointReferences?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message