This chapter explains how to access services from your ActiveGrid application. Your application can access Web services, such as SOAP services and RSS feeds or
local services, such as custom Python or PHP code. This chapter contains the following sections:
A service, in an ActiveGrid application, is a group of one or more operations that is specified in a
Service Definition file for that application. In an ActiveGrid application, a service can be a SOAP service, a REST service, an RSS Feed, or your own custom Python or PHP code. ActiveGrid bases the
Service Definition file on an industry standard, the Web Services Definition Language (WSDL) document.
Service Definition files end in the
.wsdl suffix.
ActiveGrid uses Service Definition files to orchestrate communication to and from services. Each service publishes the list of
operations that it supports in a WSDL file. Each operation specifies an
Input Message and an
Output Message that defines the inputs and outputs for that operation. ActiveGrid applications can call the service operation by sending a
request (as specified by the operation’s
Input Message) and receiving a
response (as specified by the operation’s
Output Message):
•
|
Each operation has an Input Message that specifies the input parameters for that operation. For each input parameter the operation takes, the Input Message defines a Message Part.
|
•
|
Each operation has an Output Message that contains a Message Part specifying the data that operation returns.
|
Defining a Message Part is just like declaring a variable. You name the
Message Part and you specify the data type, which can be a simple type or a complex type. (Web services have only one message part in each Input and Output Message).
•
|
SOAP services. SOAP (Simple Object Access Protocol) is a standard XML protocol for exposing and calling Web services. A SOAP service is described by a WSDL document, often available through a URL from the service itself.
|
•
|
RSS Feeds. RSS (Really Simple Syndication) defines services that provide periodically-updated lists of items. Many Web sites now provide a syndication feed that news readers and blog summaries may subscribe to. You can add a feed to ActiveGrid applications by registering the URL. ActiveGrid then connects to the service and automatically generates appropriate WSDL. Supported versions include RSS 0.91, RSS 2.0, Atom 0.3, and Atom 1.0.
|
•
|
REST Services. A REST (Representational State Transfer) Web Service is comprised of resources accessed through unique URLs (requests) and returned as XML responses. An XML Schema typically defines the structure of those XML responses. Before you can add a REST service to the ActiveGrid environment, you need to generate a WSDL document describing how the service will be used.
|
•
|
Local Services. You can also implement your own PHP or Python service according to a simple, well-defined interface. Use the Service Definition Editor to describe the service's API and register it in the ActiveGrid environment. The local service is then accessible to applications. See Adding a Local Service to an Application.
|
Your ActiveGrid Applications can consume local services (your own custom Python or PHP code, for example) as well as external Web services. For a service to be accessible to an ActiveGrid Application, it must be registered with the ActiveGrid Studio.
Use the Service Definition Editor to create, view, or edit any Service Definition (
.wsdl) file in your project. This could be WSDL files associated with a specific Web or local service, or it could be the project WSDL file, which holds the session information. Note that you do not edit WSDL files for external Web services.
To open the Service Definition Editor, open the application in the ActiveGrid Studio, and double-click on the WSDL (
.wsdl) file in the Project Panel. The Service Definition Editor appears.
•
|
Service Definition Editor: Displays the available operations in the WSDL file, as well as the input and output messages for the selected operation.
|
The Service Definition Editor panel groups items into folders:
•
|
Schema: The Schema folder defines schema for the session.
|
•
|
Page Messages: The Page Messages folder defines the messages for each Page.
|
•
|
Local Service (Port Types): The Local Service folder contains service operations that you’ve defined, along with the input and output messages for each operation.
|
•
|
Insert Operation: Launches the WSDL Operation wizard to help you add a new operation. You’re prompted to type a name for the operation and select (or create) appropriate input and output messages for it. You can add a new operation only to an existing Local Service (Port Type).
|
•
|
Insert Message: Create a new message. A dialog prompts you to name the message. Once the message is created, you can add parts to the message.
|
•
|
Insert Message Part: Launches a message part tool to allow you to add a message part to an Input or Output message. Click the Add button in the tool. A new row appears in the list of message parts. Type in a name for the new message part, and select a type from the drop-down list.
|
•
|
Edit Code: To edit an existing operation, select the operation from the Operations list and then click the Edit Code button. Do not edit operations published in WSDLs for external Web services.
|
Before a service may be used in an application, it must first be registered in the ActiveGrid development environment. Once a service is registered, it will be available to the application.
•
|
From the Type pull-down list, select SOAP.
|
•
|
Click the Download button to the right of the WSDL Path field and type the URL where the WSDL file is published, then click OK. Make sure to type in the complete URL (for example, http://www.google.com/apis).
|
•
|
The Save WSDL As dialog appears. Browse to the directory where you want to store the WSDL file locally, type in a name for the file, and click Save.
|
5.
|
Click OK. The SOAP Service is now registered with the ActiveGrid Studio and you can add operations from the service to your ActiveGrid Applications.
|
The WSDL file for your SOAP service defines the URL where the service actually resides. In some cases you want to override this URL, typically for testing purposes. To override the Service URL defined in the WSDL, follow these steps:
4.
|
In the Service and Port fields, type in the service name and port name for the service as they are defined in the WSDL file. For example, in the Google Search demo application, the following lines at the bottom of the GoogleSearch23.wsdl file define the service and port:
|
So, for the Google Search demo application, you would type in GoogleSearchService for the service name and
GoogleSearchPort for the port name.
5.
|
In the Override URL field, type in the URL you want to use for the override.
|
For SOAP services that return lots of results in scrolling or paging tables (search results for example) you might want to implement Next and Previous paging functionality. In order for the ActiveGrid runtime to know how to handle Next and Previous for an external service, you need to create an
extensions file for that service.
The extensions file defines the Next and Previous operations so that the ActiveGrid runtime can correctly interpret them. The extensions file can also define any additional operations that you want to perform for the service. To get an idea of how extensions files work, look at the example in
An Example Extensions File. For now, if you need an extensions file, you should contact ActiveGrid.
4.
|
Click the Browse button to the right of the Extensions File field and browse to the extensions file. Make sure the Extensions file is selected in the Extensions File field.
|
5.
|
Click OK. The extensions file is now registered with the SOAP Service.
|
The following extensions file was written to add Next and Previous functionality to the Googlezon demo that is included in the ActiveGrid Studio. Note that the extensions file,
GoogleSearch23.wsdlxt, does not appear in the Project Panel. It is located in the same directory as the
.wsdl file for the project, (
GoogleSearch23.wsdl).
When you register an RSS Service, the ActiveGrid Studio generates a WSDL for the service. To register an RSS Feed for use in ActiveGrid Applications, follow these steps:
•
|
In the Name field, type in a name for the service.
|
•
|
From the Type pull-down list, select RSS.
|
•
|
In the Feed URL field, type in URL for the RSS Feed.
|
•
|
Click the Test button to check that the feed is working.
|
5.
|
Click OK. The RSS Service is now registered with the ActiveGrid Studio and you can add the feed to your ActiveGrid Applications.
|
In order to register a REST service for use in ActiveGrid Applications, you must first construct a WSDL file that describes the request and response messages for the service. To see an example of a WSDL file constructed for a Web Service, open the Amazon REST service demo that is included in the ActiveGrid Studio and look at the WSDL file
AmazonREST.wsdl.
In order to register a local service, you need a WSDL file that defines the service operations and their inputs and outputs. When you use the ActiveGrid Studio to create a new local service. To register an existing local service for use in ActiveGrid Applications, follow these steps:
•
|
In the Name field, type in a name for the service.
|
•
|
From the Type pull-down list, select Local.
|
•
|
In the WSDL Path field, type in the path to the WSDL file for the local service, or click the Browse button to browse to it.
|
•
|
In the Code File field, type in the path to the code file for the local service, or click the Browse button to browse to it.
|
5.
|
Click OK. The local service is now registered with the ActiveGrid Studio and you can invoke it from your ActiveGrid Applications.
|
Before you can add a SOAP or RSS service to your application, you need to register it in the ActiveGrid Studio (
Registering Services). Once your service is registered, you can include it in your application:
In order to create a Page based on a SOAP operation, you either need a SOAP service that is already registered with an ActiveGrid Application or you need to have identified a service that you can register when you create the
Page.
In either case, you need to have a thorough knowledge of the WSDL file that defines the SOAP operation. You need to understand the WSDL file that defines the service, you need to know the operations defined by the service, and you need a clear understanding of all the messages and their parts, that you plan to use.
To invoke a SOAP service from an application, open the Page Flow (
.bpel) file for your application and right-click to bring up the Page Flow Editor menu. Choose the
Insert Service Call and Response... option. This launches the Service Invocation Wizard, which steps you through the process of invoking the SOAP service. For a step-by-step walkthrough on the Service Invocation Wizard, refer to the
ActiveGrid Studio Tutorial. Look at the tutorial on Creating a New Web services Application.
When you register an RSS, you are essentially registering the URL for the feed (
Registering an RSS Service). ActiveGrid then connects to the service and automatically generates a WSDL for the service. ActiveGrid Applications use WSDL to access all external Web services, even non-SOAP services. To add the RSS feed to your application, you add an
Action that calls the RSS service and you create a
Page that displays the response from the service.
1.
|
Open the Page Flow ( .bpel) file for your application.
|
3.
|
From the Service list, select the RSS service that you want to access. The Service list contains all the services that are currently registered. If the service you want does not appear in the list, click the New... button to register a new RSS feed ( Registering a SOAP Service).
|
4.
|
Click Next. The Pick an Operation screen appears.
|
5.
|
Select the operation that you want to access and click Next. The Use Standard Result Page? screen appears. If you want the ActiveGrid Studio to automatically generate a Page to display the RSS feed, leave this box checked. If you want to create your own Page to show the RSS feed, click to uncheck this box. Click Next.
|
In the How to Get to the Request Page screen you specify how you want users to access the request
Page. You have two choices:
•
|
Insert a button that links to the request page. This choice inserts a button into a selected Page. When users click that button, the RSS feed result is loaded. When you choose this option, make sure to also select a Page from the pull-down list. The Page you select will contain a button linking to the request Page.
|
•
|
Include the request page in another Page. This choice includes the request as part of a selected Page. You can edit the layout by editing the selected Page in the Page Editor. When you choose this option, make sure to also select a Page from the pull-down list.
|
Make your selection and click Next. The
Name the Pages screen appears. Here you name the
Page that shows the results of the RSS feed.
7.
|
Name the Page, then click Next. The new Action appears in the Page Flow Editor.
|
To invoke a local service from an application, open the Page Flow (
.bpel) file for your application and right-click to bring up the Page Flow Editor menu. Choose the
Insert Service Call and Response... option. This launches the Service Invocation Wizard, which steps you through the process of invoking the local service. For a step-by-step walkthrough on the Service Invocation Wizard, see the
ActiveGrid Studio Tutorial. Refer to the tutorial on Creating a New Web Services Application.
ActiveGrid supports web service response caching. It is Python-only, works for SOAP, REST, and RSS services, and can be configured by role. This feature is available only in the commercial version of the ActiveGrid Studio.
Currently you configure caching by editing the .wsdlag file for the project. Follow these steps:
3.
|
Under the ag:serviceref element, insert an ag:serviceCache element. The ag:serviceCache element has the following attributes:
|
where operation-name is the name of the web service operation for which you’re configuring caching.
where seconds is the number of seconds that an individual response will remain in the cache after an access (default is 600 seconds)
where role1,
role2 and so on are the roles for which you’re disabling caching. Authenticated users who are in any of these roles
do not use cached data. They always call the web service and get “live” data (which then updates the cache).
Here's an example of the USHolidayDates.wsdlag with no caching:
After you add the ag:serviceCache element, the file might look like this:
In this example, everybody gets caching on the GetGoodFriday operation, except users who possess the
monster role. The cache duration for this operation's responses is one minute.
When you invoke a service in an ActiveGrid application, the ActiveGrid Studio adds the
Service Definition (
.wsdl) file for that service to your project folder. It also creates a
.wsdlag file and adds that to your project folder as well. Each
.wsdl file in an ActiveGrid project has an associated
.wsdlag file.
The .wsdlag file provides the service references for the service. The deployment wizard uses these service references to deploy the application. You can edit the
.wsdlag file by double-clicking on it in the Project Panel. The file appears in a very simple editor. You don’t typically need to edit this file manually.