BlazeDS Developer Guide

Using destinations

You typically connect an RPC component to a destination defined in the services-config.xml file or a file that it includes by reference, such as the proxy-config.xml file. A destination definition is a named service configuration that provides server-proxied access to an RPC service. A destination is the actual service or object that you want to call.

Destination definitions provide centralized administration of RPC services. They also enable you to use basic or custom authentication to secure access to destinations. You can choose from several different transport channels, including secure channels, for sending data to and from destinations. Additionally, you can use the server-side logging capability to log RPC service traffic.

You have the option of omitting the destination and connecting to HTTP and web services directly by specifying the URL of the service. For more information, see Using HTTPService and WebService without a destination. However, you must define a destination when using the RemoteObject component.

You configure HTTP services and web services as HTTPProxyService destinations. The following example shows a HTTPProxyService destination definition for an HTTP service in the proxy-config.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<service id="proxy-service" class="flex.messaging.services.HTTPProxyService">
    ...

    <destination id="myHTTPService">
        <properties>
            <!-- The endpoint available to the http proxy service -->
            <url>http://www.mycompany.com/services/myservlet</url>
            <!-- Wildcard endpoints available to the http proxy services -->
            <dynamic-url>http://www.mycompany.com/services/*</dynamic-url>
        </properties>
    </destination>
</service>

Using an RPC component with a server-side destination

The destination property of an RPC component references a destination configured in the proxy-config.xml file. A destination specifies the RPC service class or URL, the transport channel to use, the adapter with which to access the RPC service, and security settings.

To declare a connection to a destination in MXML, set the id and destination properties in the RPC component. The id property is required for calling the services and handling service results. The following example shows HTTPService and WebService component declarations in MXML:

<?xml version="1.0"?>
<!-- ds\rpc\RPCMXML.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:HTTPService
        id="yahoo_web_search"
        useProxy="true"
        destination="catalog"/>

    <mx:WebService
        id="adbe_news"
        useProxy="true"
        destination="ws-catalog"/>
</mx:Application>

When you use a destination with an HTTPService or WebService component, you set its useProxy property to true to configure it to use the HTTPProxyService. The HTTPProxyService and its adapters provide functionality that lets applications access HTTP services and web services on different domains. Additionally, the HTTPProxyService lets you limit access to specific URLs and URL patterns, and provide security.

Note: Setting the destination property of the HTTPService or WebService component automatically sets the useProxy property to true.

When you do not have BlazeDS or do not require the functionality provided by the HTTPProxyService, you can bypass it. You bypass the proxy by setting the useProxy property of an HTTPService or WebService component to false, which is the default value. Also set the HTTPService.url property to the URL of the HTTP service, or set the WebService.wsdl property to the URL of the WSDL document. The RemoteObject component does not define the useProxy property; you always use a BlazeDS destination with the RemoteObject component.

Configuring a destination

You configure a destination in a service definition in the proxy-config.xml file. The following example shows a basic server-side configuration for a WebService component in the proxy-config.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<service id="proxy-service" class="flex.messaging.services.HTTPProxyService">

    <properties>
        <connection-manager>
            <max-total-connections>100</max-total-connections>
            <default-max-connections-per-host>2</default-max-connections-per-host>
        </connection-manager>
        <allow-lax-ssl>true</allow-lax-ssl>
    </properties>

    <!-- Channels are typically defined in the services-config.xml file. -->
    <default-channels>
        <channel ref="my-http"/>
        <channel ref="my-amf"/>
    </default-channels>

    <!-- Define the adapters used by the different destinations. -->
    <adapters>
        <adapter-definition id="http-proxy"
            class="flex.messaging.services.http.HTTPProxyAdapter" 
            default="true"/>
        <adapter-definition id="soap-proxy" 
            class="flex.messaging.services.http.SOAPProxyAdapter"/>
    </adapters>

    <!-- HTTPService destination uses the default adapter. -->
    <destination id="catalog">
        <properties>
            <url>/{context.root}/testdrive-httpservice/catalog.jsp</url>
        </properties>
    </destination>

    <!-- WebService destination uses the SOAPAdapter. -->
    <destination id="ws-catalog">
        <properties>
            <wsdl>http://server.org/services/ProductWS?wsdl</wsdl>
            <soap>*</soap>
        </properties>
        <adapter ref="soap-proxy"/>
    </destination> 
</service>

HTTPService and WebService components connect to HTTPProxyService destinations. Therefore, the class attribute of the <service> tag specifies the HTTPProxyService class.

The adapter is server-side code that interacts with the remote service. Specify the HTTPProxyAdapter with a destination defined for the HTTPService component, and the SOAPAdapter for the WebService component.

This destination uses an HTTP or an Action Message Format (AMF) message channel for transporting data. Optionally, it could use one of the other supported message channels. Message channels are defined in the services-config.xml file, in the channels section under the services-config element. For more information, see Channels and endpoints.

Revised: 2/27/09:

You use the url and dynamic-url elements to configure HTTP service URLs in a destination. These elements define which URLs are permitted for a destination. The following table describes those elements:

Element

Description

url

(Optional) Default URL.

The HTTPService URL could be at a domain that is different from the one hosting your SWF file and therefore cannot be requested directly from Adobe Flash Player due to the sandbox security restrictions the player enforces. When that is the case, you can use the Proxy Service to proxy the request. You establish a set of URLs that you permit it to proxy for you. In a Proxy Service destination you configure the URL in the url property to instruct the Proxy Service to allow requests to be proxied to this URL.

The url property also lets you avoid hard coding the HTTP URL into your MXML file by specifying the destination name instead of the HTTP URL.

dynamic-url

(Optional) HTTP service URL patterns. You can use more than one dynamic-url entry to specify multiple URL patterns. Flex matches these values against url property values that you specify in client-side service tags or ActionScript code.

You use the wsdl and soap elements to configure web service URLs in a destination. These elements define which URLs are permitted for a destination.

The following table describes those elements:

Element

Description

wsdl

(Optional) Default WSDL URL.

When you use a WebService component in a Flex application, the first thing that happens is an HTTP GET request is made to a URL to load the WSDL document for the web service. The URL could be at a domain that is different from the one hosting your SWF file and therefore cannot be requested directly from Adobe Flash Player due to the sandbox security restrictions the player enforces. When that is the case, you can use the Proxy Service to proxy the request. You establish a set of URLs that you permit it to proxy for you. In a Proxy Service destination you configure the WSDL URL in the wsdl property to instruct the Proxy Service to allow requests to be proxied to this URL.

The wsdl property also lets you avoid hard coding the WSDL URL into your MXML file by by specifying the destination name instead of the WSDL URL.

soap

(Optional) SOAP endpoint URL.

In a WSDL document, there is a port section, usually at the end of the file, that describes the location of the SOAP endpoints to handle web service requests. These URLs are used in subsequent HTTP POST requests that send SOAP-formatted requests and corresponding SOAP-formatted responses. You add these URLs using the soap properties in the destination configuration. You typically use a soap property to define a SOAP endpoint URL pattern for each operation in a WSDL document. You use more than one soap entry to specify multiple SOAP endpoint patterns.

You can use wildcards in these URLs because in more complex WSDLs you can have multiple services, multiple ports, and therefore multiple SOAP address locations.

Example:

<soap>http://www.weather.gov/forecasts/xml/SOAP_server/*</soap>

Using <soap>*</soap> on an unprotected destination is not a good idea because you are effectively setting up a public anonymous relay. If you do want to use a very lenient wildcard, you can set a role-based J2EE security restriction and require authentication on the message broker so that only authenticated requests are processed.

Note: If you use endpointURI property values in client-side service tags or ActionScript code, Flex matches the values specified in soap properties against those.

Using HTTPService and WebService with the default destination

In the following situation, a component uses a default destination:

  • You set the useProxy property to true
  • You do not set the destination property
  • You set the HTTPService.url property or the WebService.wsdl property

The default destinations are named DefaultHTTP and DefaultHTTPS. The DefaultHTTPS destination is used when your url or wsdl property specifies an HTTPS URL.

By setting the url or wsdl property, you let the component specify the URL of the remote service, rather than specifying it in the destination. However, since the request uses the default destination, you can take advantage of BlazeDS. Therefore, you can use basic or custom authentication to secure access to the destination. You can choose from several different transport channels, including secure channels, for sending data to and from destinations. Additionally, you can use the server-side logging capability to log remote service traffic.

Configure the default destinations in the proxy-config.xml file. Use one or more dynamic-url parameters to specify URL patterns for the HTTP service, or one or more soap parameters to specify URL patterns for the WSDL of the web service. The value of the url or wsdl property of the component must match the specified pattern.

The following example shows a default destination definition that specifies a dynamic-url value:

<service id="proxy-service" class="flex.messaging.services.HTTPProxyService">
    ...

    <destination id="DefaultHTTP">
        <channels>
            <channel ref="my-amf"/>
        </channels>
    
        <properties>
            <dynamic-url>http://mysite.com/myservices/*</dynamic-url>
        </properties>
        ...
    </destination>
</service>

Therefore, set the HTTPService.url property to a URL that begins with the pattern http://mysite.com/myservices/. Setting the HTTPService.url property to any other value causes a fault event.

The following table describes elements that you use to configure the default destinations:

Parameter

Description

dynamic-url

Specifies the URL pattern for the HTTP service. You can use one or more dynamic-url parameters to specify multiple patterns. Any request from the client must match one of the patterns.

soap

Specifies the URL pattern for a WSDL or the location of a web service. You can use one or more soap parameters to specify multiple patterns. The URL of the WSDL, or the URL of the web service, must match one of the patterns. If you specify a URL for the wsdl property, the URL must match a pattern,


 

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/blazeds/1/blazeds_devguide/rpc_httpws_04.html