The process of creating Web Services is automated by the Web Service Creation Wizard in the Dynamo Administration UI. This wizard guides you through the steps of selecting a Nucleus component and method, specifying input parameters and other settings; it then automatically creates the Web Service by performing the following steps:
Create the service endpoint interface that specifies the method to be exposed
Create the service endpoint class that implements the service endpoint interface and is responsible for handing incoming SOAP requests
Create the WSDL document that describes the resources required by the service endpoint class, as well as its inputs and outputs
Create the
web.xmlfile for the Web application of which the service is a partCreate the JAX-RPC deployment descriptor (
webservices.xml) and mapping fileBuild the runtime classes
Package these elements in a JSR 109 compliant EAR file
These steps are described in more detail in the Anatomy of a Web Service section.
The wizard uses the component /atg/webservice/WebServiceGenerator to perform the actual work of generating the service. This component, which is of class atg.webservice., performs all of the operations listed above, either through its own methods or through other components it refers to.
WebServiceGeneratorImpl
Using the Wizard
The top-level page of the Dynamo Administration UI includes a Web Service Administration link. This link takes you to the Web Service Administration page, which has three links for working with Web Services:
Web Service Registry – Takes you to a page for viewing and managing currently loaded Web Services. The Web Services registry is discussed in the section Managing Web Services
Web Service Security Manager – Enables you to create and edit Web Service security configurations. These security configurations can be used to define which users can access specific Web Services. When you create a Web Service, you have the option of associating a security configuration with the service. Security configurations are discussed in the section Web Service Security
Web Service Creation Wizard – Takes you to a page with links for creating each of the three kinds of Web Services (Component Method Web Service, JMS Message Web Service, Repository Web Service)
To create a Web Service that invokes a method on a Nucleus component, starting from the Web Service Administration page:
Click the Web Service Creation Wizard link. This takes you to a page titled Select Type, where you can select the type of Web Service to create.
Click the Component Method Web Service link. This takes you to the Select Nucleus Component page.
On the Select Nucleus Component page, specify the pathname of the Nucleus component you want to create the Web Service from. You can either enter the pathname directly in the field at the top of the page and then click the Next button, or you can use the component browser below it to navigate to the component and select it.
On the Select A Method page, select the method you want to expose as a Web Service.
If the method requires any input parameters, the Set Parameter Names page provides you with fields for specifying the names of these parameters. The names you specify are used for the parameters of the Web Service call, and can be anything you like.
When the Web Service is called, the service passes the values of these parameters to the parameters of the exposed Nucleus method. There is thus a one-to-one correspondence between the parameters of the Web Service call and the parameters of the underlying Nucleus methods.
The next two pages are titled EAR Name & Servlet Settings and Enterprise and Web Application Settings. When the wizard creates a Web Service, it packages it in a WAR file, which is in turn packaged in an EAR file. It is possible to have any number of services in a single Web application (WAR file), and any number of Web applications in a single Enterprise application (EAR file). This flexibility gives you a good deal of control over how you deploy your Web Services. For each new Web Service, the wizard can do any of the following:
Create a new EAR file for the service, and put it in a WAR file within the EAR file
Use an existing EAR file, and put the service in a new WAR file within it
Put the service in an existing WAR file within an existing EAR file
To add a Web Service to an existing EAR file, you specify that file as the EAR file name on the EAR Name & Servlet Settings page. The Web Application Settings page then gives you the choice of creating a new Web application for the service, or adding the service to an existing Web application.
The wizard also gives you the option of specifying the host name and port number for a Web Service, or of leaving these fields blank. If you leave the fields blank, the values are dynamically assigned at runtime from the URL used for the WSDL file request.
The Session & Security Options page allows you to specify whether the Web Service should be executed within the context of an HTTP session. The wizard gives you these options:
Neither provide a session nor security constraints
Provide a session, but no security constraints
Provide both a session and security constraints
If you want to call the Web Service from a client that uses sessions or session sharing, you must choose one of the last two options. If you choose the last option, the wizard then prompts you to select a security configuration. See Web Service Security for information about security configurations for Web Services.
On the Create EAR File page, click the Create EAR File button to create the Web Service. If there is already an EAR file with the specified name, the wizard first appends
.oldto the name of the existing file so that new file does not overwrite it.
Once you have created an EAR file, you must deploy it in order to run the Web Services in it. See the Deploying Web Services section for more information.
Naming Restrictions
Most of the class names and filenames for Web Services are generated automatically by the wizard. As a result, certain circumstances can result in naming conflicts. For example, if you create a Web Service from a Nucleus method, you cannot then create a second Web Service from another method with the same name (such as an overloaded method) and put it in the same WAR file, even if the two methods have different signatures or capitalization. If you attempt to do this, the second Web Service simply overwrites the first.
To prevent the second service from overwriting the first, put the second service in a different WAR file. In addition, be sure to give the second WAR file a different context root from the first WAR file. (The default value for the context root in the wizard is based on the method name, so you will need to change the value when you run the wizard.) It is then be possible to differentiate calls to the two services based on their context roots.
