Title: Endpoint References
Category: documentation

<a name="EndpointReferences-Introduction"></a>
## Introduction
An endpoint reference holds information to call a service. The simplest endpoint reference is usually an URL but it can also be much more complex such as holding a message id, a reply-to address or custom properties.

In BPEL, endpoint references (aka EPRs) are modeled as partner link roles. When defining a partner link, two roles maybe defined,  `myRole` and `partnerRole`:

    :::xml
    <partnerLink name="responderPartnerLink" partnerLinkType="test:ResponderPartnerLinkType"
                 myRole="main" partnerRole="responder" initializePartnerRole="yes"/>


Both `partnerRole` and `myRole` represent EPRs. So when assigning partner link roles or invoking partners, you are using EPRs behind the scene.

<a name="EndpointReferences-ODEandEndpointReferences"></a>
## ODE and Endpoint References

<a name="EndpointReferences-TypesofEPRs"></a>
### Types of EPRs

The ODE runtime supports 4 types of EPRs:

* A simple URL or a URL in the location attribute of the binding. See [soap:address](http://www.w3.org/TR/wsdl#_soap:address) and [http:address](http://www.w3.org/TR/wsdl#_http:address) WSDL 1.1 binding.
* A [WS-Addressing](http://www.w3.org/TR/ws-addr-core/) [EndpointReference](http://www.w3.org/TR/ws-addr-core/#eprinfomodel).
* A [WSDL 1.1](http://www.w3.org/TR/wsdl) [service element](http://www.w3.org/TR/wsdl#_services).
* A [WSDL 2.0](http://www.w3.org/TR/wsdl20/) [endpoint element](http://www.w3.org/TR/wsdl20/#Endpoint).

We recommend the two first solutions to interact with the engine. The first one is just the easiest and for the case where you need more robustness, WS-Addressing is the most popular second choice.

To show you how these EPRs look like and how they can be assigned to partner links roles here are some examples:


    <assign>
    
      <!-- Simple URL, without the wrapper -->
      <copy>
        <from>
          <literal>http://localhost:8080/ode/dynresponder</literal>
        </from>
        <to partnerLink="responderPartnerLink"/>
      </copy>
     
      <!-- Simple URL, wrapped in an soap:address element -->
      <copy>
        <from>
          <literal>
            <service-ref>
              <soap:address location="http://localhost:8080/ode/dynresponder"/>
            </service-ref>
          </literal>
        </from>
        <to partnerLink="responderPartnerLink"/>
      </copy>
    
      <!-- WS-Addressing EPR, without the wrapper -->
      <copy>
        <from>
          <literal>
            <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
              <wsa:To>http://localhost:8080/ode/dynresponder</wsa:To>
            </wsa:EndpointReference>
          </literal>
        </from>
        <to partnerLink="responderPartnerLink"/>
      </copy>
    
      <!-- WS-Addressing EPR, with the wrapper -->
      <copy>
        <from>
          <literal>
            <service-ref>
               <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing">
                 <wsa:To>http://localhost:8080/ode/dynresponder</wsa:To>
               </wsa:EndpointReference>
            <service-ref>
          </literal>
        </from>
        <to partnerLink="responderPartnerLink"/>
      </copy>
    
      <!-- WSDL1.1 EPR, without the wrapper -->
      <copy>
        <from>
          <literal>
             <wsdl:service xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" name="DynService" targetNamespace="http://org.apache.ode/examples/dynservice">
               <wsdl:port name="DynPort">
                       <soap:address location="http://localhost:8080/ode/dynresponder"/>
               </wsdl:port>
             </wsdl:service> 
         </literal>
        </from>
        <to partnerLink="responderPartnerLink"/>
      </copy>
    
      <!-- WSDL2.0 EPR, with the wrapper -->
      <copy>
        <from>
          <literal>
             <service-ref>
             <wsdl:service xmlns:wsdl="http://www.w3.org/2006/01/wsdl" name="DynService" targetNamespace="http://org.apache.ode/examples/dynservice">
               <wsdl:port name="DynPort">
                       <soap:address location="http://localhost:8080/ode/dynresponder"/>
               </wsdl:port>
             </wsdl:service> 
             </service-ref>
         </literal>
        </from>
        <to partnerLink="responderPartnerLink"/>
      </copy>
    
    </assign>


Normally BPEL requires wrapping EPRs with inside a `service-ref` element, however ODE relaxes this requirement for ease of use and increased interoperability with existing services.  If the `service-ref` element is absent, the EPR is automatically wrapped inside one on the fly. Moreover, ODE automatically detects the different EPR types when assigning to a partner link role. If you need to use WS-Addressing sessions (@see appropriate page), then you will have to use `wsa:EndpointReference` EPRs.

You can just as well assign EPRs to/from variables to pass them around and enable more dynamic communication patterns.

<a name="EndpointReferences-PassingEndpointReferences"></a>
## Passing Endpoint References

To pass endpoint references around and manipulate them, you usually need to assigne them to variables. The EPR can then be sent in a message and reassigned to another partner link. This lets you model complex scenarii where you don't know the address of your partner beforehand or where you select one partner among many others.

The type of the variable that will hold your EPR defines the type of the EPR that it will contain. For example if you define a message in your WSDL document that looks like this:


    <wsdl:message name="EndpointMessage">
      <wsdl:part name="payload" element="xsd:string"/>
    </wsdl:message>


ODE will automatically put a simple URL EPR when you assign this message part:


    <variable name="myEndpoint" messageType="resp:EndpointMessage"/>
    ...
    <assign>
      <copy>
        <from partnerLink="mainPartnerLink" endpointReference="myRole"/>
        <to variable="myEndpoint" part="payload"/>
      </copy>
    </assign>


Now if you want to manipulate a WS-Addressing EPR, the only thing you have to change in the above examples is the message part type. So your message will then look like this:

<wsdl:message name="EndpointMessage">
  <wsdl:part name="payload" element="wsa:EndpointReference"/>
</wsdl:message>

Once your EPR has been assigned to a variable and set, say, to another process, you just need to reassign it to a partner link `partnerRole` to use it:


    <assign>
      <copy>
        <from variable="eprmessage" part="payload"/>
        <to partnerLink="mainPartnerLink"/>
      </copy>
    </assign>
    <invoke name="eprcall" partnerLink="mainPartnerLink"
           portType="resp:MSMainPortType" operation="call" inputVariable="eprmessage"/>


For a complete example check [DynPartner](http://svn.apache.org/repos/asf/ode/trunk/distro/src/examples-war/DynPartner/) in the engine examples.