Generating and Publishing Web Services

This topic describes how to publish BEA Liquid Data for WebLogic^TM stored queries as Web services. It contains the following sections:

• Viewing a Demo
• About Web Services
• Creating a New Web Service from a Stored Query
• Modifying a Web Service
• Deleting a Web Service
• Testing a Generated Web Service
• Managing the Deployment of a Generated Web Service
• Invoking Published Web Services

Using the Administration Console, you can publish Liquid Data stored queries as Web services. Web-based applications can then invoke Liquid Data queries as Web service clients.

 

---

Viewing a Demo

Generate Web Service Demo... If you are looking at this documentation online, you can click the "Demo" button to see a viewlet demo showing how to use the Liquid Data Administration Console to generate a Web service from a stored query. The viewlet also demonstrates how to test the generated Web service in BEA WebLogic Workshop^TM. The demo assumes that you have already stored the query you want to use in the Liquid Data Repository.

 

---

About Web Services

Web services are a type of service that can be shared by, and used as components of, distributed Web-based applications. Web services communicate with clients (both end-user applications or other Web services) through XML messages that are transmitted by standard Internet protocols, such as HTTP. Web services endorse standards-based distributed computing. Currently, popular Web Service standards are SOAP (Simple Object Access Protocol), WSDL (Web services description language) and UDDI (Universal Description, Discovery, and Integration).

 

---

Creating a New Web Service from a Stored Query

This section describes how to generate a Web service from a stored query in the server repository. For each stored query, you can have up to one generated Web service.

Notes: The names of stored queries to be generated as Web services must begin with an alphabetic character, followed by other alphabetic characters or numbers. The file name must also have an .xq suffix. For more information, see Naming Conventions for Stored Queries in Building Queries and Data Views.

To create a new web service from a stored query:

1. In the left pane of the Administration Console, click the Liquid Data node.

2. In the right pane, click the Repository tab.

3. Click the stored_queries directory.

4. If the stored query resides in a subdirectory of the stored_queries directory, navigate to the subdirectory.

5. Next to the stored query, click Generate Web Service.

   Note: If the Generate Web Service link is not available, then a Web service has already been generated for this stored query.

   The Administration Console prompts you to select a target schema for the web service.

   
    

   Table 20-1 Generating a Web Service  

   Field

   Description

   Target Schema

   Target schema used by this query. The target schema you specify here must be available in the Liquid Data Repository. It should also be the same target schema you used to build and test the query, or at least match the structure of the target schema. A target schema used for generating a web service must have the following XML namespace: http://www.w3.org/2001/XMLSchema The line in the XML file (usually the second or third line) should like as follows: <xsd:schema xmlns:xsd = "http://www.w3.org/2001/XMLSchema">

   
    

6. Enter the name of the target schema in the schemas directory, or click Browse Repository to select it by browsing.

7. Click Generate.

   The Administration Console generates the Web service, storing the generated Web service as an EAR (enterprise archive) file in the web_services_gen directory, using the name of the stored query as the file name prefix. For example, the generated web service for a stored query named order.xq would be order.ear. The WSDL of the generated Web service is dynamically generated at runtime by the EAR file after it is deployed successfully.

   The Administration Console automatically deploys the EAR file to all nodes in the currently active domain. If you subsequently need to manage this EAR file, such as undeploying or redeploying it, see Managing the Deployment of a Generated Web Service.

   The Administration Console shows a confirmation message if it completes the process successfully, displaying the URL of the generated web service, as shown in the following example:

   Note: Users should save the URL for future use.

   The URL of the WSDL of a generated Web service has the following pattern:

   http://HOSTNAME:PORT/liquiddata/query_name/webservice?WSDL

   For example, if the stored query is named order.xq, then the URL of its WSDL is http://localhost:7001/liquiddata/order/webservice?WSDL.

If the associated stored query is modified or deleted, then this generated Web service is deleted automatically. If the stored query has been modified, you need to explicitly create it again using the instructions in this section.

 

---

Modifying a Web Service

You cannot directly modify a generated Web service. If the associated stored query is modified or deleted, the generated Web service is deleted automatically.

To modify a Web service:

1. Delete the Web service according to the instructions in Deleting a Web Service.

2. Regenerate the Web service according to the instructions in Creating a New Web Service from a Stored Query.

 

---

Deleting a Web Service

You can delete a Web service that you no longer need or that you want to regenerate.

Note: A Web service is automatically deleted if its associated stored query is subsequently changed or deleted.

To directly delete a Web service:

1. In the left pane of the Administration Console, click the Liquid Data node.

2. In the right pane, click the Repository tab.

3. Click the web_services_gen directory.

4. Scroll to find the Web service that you want to delete.

5. Click the delete icon next to the Web service you want to delete.

6. In the left pane of the Administration Console, click the Web Service Components node.

7. Scroll to find the Web service that you want to delete, and then click the delete icon next to it.

 

---

Testing a Generated Web Service

You can use BEA WebLogic Workshop^TM to test a Web service that you have generated with the Administration Console.

Note: Before you begin, make sure that the WebLogic Workshop Example server and the Workshop tool use a different port number from the one that the Liquid Data server uses. For example, if the Liquid Data server uses port 7001, then the WebLogic Workshop Example server should be started on a different port (such as 7010) and the Workshop tool should be configured to access that different port.

To test the Web service:

1. Start WebLogic Workshop.

2. In the Design View, click Add Control, and then select Add Service Control.

3. In the Add a Service Control dialog box, specify a variable name for the service control (such as testws).

4. Click Create a Service Control from a WSDL, and then enter the URL of the generated Web service.

5. Click Add Operation, select Add Method, and specify a method name (such as test).

6. Click the new method to edit it.

7. In the Source View, scroll to the import section and copy the name of the AnonType_* associated with the Web service.

8. In the method declaration, replace void with the AnonType_* type, as in the following example:

   public AnonType_CustomerOrderReport test()

9. In the method body, add a return statement and specify the name of the Service Control you specified earlier (such as testws), as in the following example:

   public AnonType_CustomerOrderReport test()

   {

         return testws

   }

10. Select the testws variable. WebLogic Workshop shows the operation name of the generated Web service in bold.

11. Click the operation so that the source reads:

    public AnonType_CustomerOrderReport test()

    {

    return testws.order();

    }

12. Click the Start button to get to the Test Form.

13. In the Test Form, click the method name (such as test).

14. WebLogic Workshop runs the test, displaying the request (External Service Request) and the query result (External Service Response) in the Test Form.

 

---

Managing the Deployment of a Generated Web Service

When you create a Web service, the Administration Console automatically deploys the generated EAR file to all nodes in the currently active domain. If you subsequently need to manage this EAR file, such as undeploying or redeploying it:

1. In the left pane, click Deployments->Applications.

2. Select the EAR file from the list.

3. Click the Deploy tab. For additional instructions, see Deploying Applications in the WebLogic Server Administration Guide.

For detailed information about WebLogic Web services, see Programming WebLogic Web Services in the WebLogic Server documentation.

 

---

Finding the Target Schema for a Generated Web Service

If you want to find the target schema for a generated web service, the target schema is stored in the generated EAR file. To view the contents of the EAR file, open the file with a utility such as WinZip. The EAR file is located in the following directory:

<ld_repository>/web_services_gen

The filename of the EAR file is generated based on the filename of the stored query from which the web service was generated. For example, if a stored query is named order.xq, the generated web service name is order.ear.

 

---

Invoking Published Web Services

You invoke Liquid Data Web services that were generated in the Administration Console using the same approach that you would use for invoking any WebLogic Web Service. For more information, see Invoking Queries in Web Service Clients in Invoking Queries Programmatically.