Creating Web Service Proxies 

Use

Some options in this procedure require that Enterprise Services Repository for SAP NetWeaver Composition Environment is installed in your system landscape.

You can create two types of proxies in the SAP NetWeaver Developer Studio:

●      Deployable proxy

A Web service client, which can and has to be deployed on the application server to be operational. A deployable proxy is consumed from an Enterprise Java Bean or a servlet and is created and configured by the responsible managing container of the application server. Deployable proxies are used through the Java EE 5 injection mechanism. You generate a deployable proxy in an Enterprise Java Bean project, or in a Dynamic Web Project in the Developer Studio.

You cannot consume a deployable proxy with a JSP application.

●      Standalone proxy

A Web service client which can be instantiated by application code. The application code can run in a standalone program. The standalone proxy can be used mainly for test purposes from within the SAP NetWeaver Developer Studio. You generate a standalone proxy in a Java project.

Basically, the procedure of creation of standalone and deployable proxies differs only in the target project in which you create the proxy. The procedure steps are the same for both proxy types.

You generate proxies using a WSDL document as a basis. You can use a WSDL document located in the Services Registry, the Enterprise Services Repository, or on a file system, or at a remote location (such as a URL). Some WSDL documents, such as those for Service Interfaces (SI) modeled in the ESR, may not contain a service, port, and/or binding information. When the framework generates a proxy, it updates the WSDL document with the necessary information. By default, if the WSDL document does not contain binding information, the Web service framework updates the WSDL and sets the binding to SOAP over HTTP. You cannot change this default setting.

If you have generated an outside-in Web service and want to generate it again based on the same WSDL document that was already imported in the SAP NetWeaver Developer Studio, you have to delete the imported WSDL document from the project in the Developer studio. You also have to delete all Java artifacts, including the implementation bean, that were generated in the result of the previous generation of the Web service. In this case, before you delete the Java artifacts, you may want to back up any implementation which you have provided in the implementation bean.

The Web service client and the Web service proxy must be in the same EAR and in the same module (EJB or Dynamic Web module).

Collision Resolution and Global Customizations

When generating proxies, collisions may arise in the mapping between names in the WSDL and the names of the corresponding Java artifacts. For example, a complex type with two elements el_1 and el1 would, by default, be mapped to a Java class with two properties with the same names (el1). As another example, long names in the WSDL document may result in long names of Java classes.

The Web service framework for proxy generation enables you to resolve potential collisions in a number of different ways:

●      You can use customization options integrated in the wizard for proxy generation. These customizations are compliant with the JAXB 2.0 specification, Chapter 7.5 <globalBinding> Declaration.

●      You can use your own external customization files to change the default behavior of the Web services generation framework to change the names of the classes, packages, types and operations in the generated endpoint. Customization files allow you to:

○       Reuse the types in more than one outside-in Web service.

○       Change the mapping between WSDL namespaces and the packages in the generated classes.

Customization files are files prepared by you in advance. Before using customization files, make sure that they are correct and comply with the Java API for XML-Based Web Services (JAX-WS) 2.0.

More information about the collision resolution options which the framework provides is available in the procedure below.

Prerequisites

●      Generating a deployable proxy

You can generate deployable proxies in an Enterprise Java Bean project, or in a Dynamic Web Project. Depending on your scenario, the respective project has to be available in the SAP NetWeaver Developer Studio:

○       An EJB project is created. The EJB module in the project is version 3.0. More information: Creating EJB 3.0 Projects in the Developer Studio

○       A Dynamic Web Project is created. The Dynamic Web Module in the project is version 2.5. More information: Creating Dynamic Web Projects

●      Generating a standalone proxy

○       A Java project is created.

●      An enterprise application project is created. The Enterprise Java Bean project or the Dynamic Web project is added to the enterprise application project.

●      The AS Java settings are configured in Window → Preferences → SAP AS Java.

●      The application server and Web service runtime are set in the SAP NetWeaver Developer Studio from Window  →  Preferences  →  Web Services  →  Server and Runtime. In the Server field, choose SAP Server, and in the Web service runtime, choose SAP NetWeaver.

●      If you want to use the WSDL of a Service Interface modeled in the ESR, open the Enterprise Service Browser.

●      If you want to use customization files, you should have them available in advance.

Procedure

       1.      Import the WSDL document, which you want to use to generate a proxy. More information: Importing WSDL Documents in the SAP NetWeaver Developer Studio.

If you want to generate a proxy based on a WSDL document of a Service Interface modeled in the ESR, you can start the wizard from the ES Browser (see the next step below). In this case, you do not need to import the WSDL document from the ESR manually. The Web service framework imports it automatically in the project folder. Note that if you use this option, you will not be able to use your own customization files.

       2.      In the Project Explorer of the J2EE perspective, choose the WSDL document, and then from the context menu, choose Web Services → Generate Client.

If you want to generate a proxy based on a WSDL document of a Service Interface modeled in the ESR, in the Enterprise Service Browser view, expand the Service Interfaces node of a software component, choose a Service Interface, and then from the context menu choose Generate Client. Note that if you use this option, you will not be able to use your own customization files.

The Web Services wizard opens.

       3.      On the Web Services screen, proceed as follows:

                            a.      Move the slider to the Develop Service position.

In this case, the Web service framework only generates the relevant artifacts (it does not deploy them on the application server).

                            b.      Under Configuration, choose Service EAR Project, and make sure that the correct service EAR project is selected in the Service project field.

                            c.      Choose Next.

If the WSDL document you are using does not contain a service, port, and/or binding information, you receive a message which informs you that the WSDL document will be updated. Choose OK.

       4.      On the Select output path screen, proceed as follows:

                            a.      If necessary, specify the output folder in which you want the Java artifacts to be generated.

                            b.      Choose the way in which you want to resolve the possible collisions in the WSDL to Java mapping during the conversion of the WSDL document to Java artifacts.

The table below provides information about the separate options and their meaning:

Collision Resolution Options

Option	Meaning
Resolve collisions interactively	The Web service framework resolves collisions based on input from you.
Prevent collisions where possible	The Web service framework resolves collisions compliant with a predefined algorithm.
Specify JAX-WS customization files	You can use JAX-WS 2.0-compliant customization files prepared in advance to apply customizations. This option is available only when the WSDL document is imported in the SAP NetWeaver Developer Studio. During the generation process, the Web service framework does not validate the external customization files you might use. You have to ensure that these files are correct and comply with the JAX-WS 2.0 specification.
Apply WSDL without customizations	The Web service framework processes the WSDL document as it is. If the WSDL document itself contains customizations in that, for example, it was manually edited, the framework will process these customizations.

Depending on the customizations level you choose on this screen, the wizard provides different options on the subsequent screens. The procedures below outline the necessary steps you need to complete as a result of the customizations level you selected at this step.

Using Interactive Conflict Resolution

       1.      On the Service, Port, Binding names selection screen, proceed as follows:

                            a.      Specify names for the service, port and binding with which you want the Web service framework to update the WSDL document. You can accept the default values.

If the WSDL document you are using already contained binding information before you imported it, you cannot edit the name of the binding.

                            b.      Choose Next.

       2.      On the Namespace – Package Mapping screen, proceed as follows:

                            a.      In the WSDL Package field, enter the name of the package in which you want the framework to generate the Java classes based on the following WSDL artifacts: service, binding, portType, and fault(s). The Java class for the service endpoint interface (SEI) has the name of the WSDL portType and is generated based on the WSDL portType and binding.

If the WSDL document imports other WSDL documents, only one package is generated and it has the name you specify.

                            b.      In the Package field, specify the name of the package which will be generated from the namespace of the XSD schema.

If the WSDL document contains or includes/imports other XSD schemas each in a different namespace, a separate package is generated for each namespace.

                            c.      Choose Next.

       3.      On the Global customizations options screen, you can apply customizations compliant with the JAXB 2.0 specification, Chapter 7.5 <globalBinding> Declaration. More information about the meaning of each option: Global Customizations.

Choose the relevant options.

       4.      Choose Next.

       5.      The Resolve Collisions screen allows you to manually resolve any collisions that may be still unresolved, such as the potential generation of long Java class names. In the Mapped to Name column, you can enter a shorter name for a Java class, or resolve any other collisions.

If there are no collisions to resolve, the list on this screen is empty.

       6.      Choose Finish.

       7.      WSDL documents which use the same schema may use the same types. If you are running the wizard on a WSDL document, for example WSDL_B, which uses the same schema as the WSDL document, for example WSDL_A, on which you have already run the wizard, the framework would have to generate Java classes based on WSDL_B that were already generated based on WSDL_A. When you run the wizard on WSDL_B, the framework can keep the “duplicate” Java classes from the previous execution of the wizard (based on WSDL_A, in our example) or override the “duplicate” Java classes with the ones from the current execution of the wizard (based on WSDL_B, in our example).

On the screen that opens, choose the existing files which you want to the framework to override with the ones from the current generation. The files that you leave deselected are kept from the previous execution of the wizard. Choose OK.

Using Automatic Conflict Resolution

       1.      On the Service, Port, Binding names selection screen, proceed as follows:

...

                            a.      Specify names for the service, port and binding with which you want the Web service framework to update the WSDL document. You can accept the default values.

If the WSDL document you are using already contained binding information before you imported it, you cannot edit the name of the binding.

                            b.      Choose Next.

       2.      On the Namespace – Package Mapping screen, proceed as follows:

...

                            a.      In the WSDL Package field, enter the name of the package in which you want the framework to generate the Java classes based on the following WSDL artifacts: service, binding, portType, and fault(s). The Java class for the service endpoint interface (SEI) has the name of the WSDL portType and is generated based on the WSDL portType and binding.

If the WSDL document imports other WSDL documents, only one package is generated and it has the name you specify.

                            b.      In the Package field, specify the name of the package which will be generated from the namespace of the XSD schema.

If the WSDL document contains or includes/imports other XSD schemas each in a different namespace, a separate package is generated for each namespace.

                            c.      Choose Next, and then choose Finish.

                            d.      WSDL documents which use the same schema may use the same types. If you are running the wizard on a WSDL document, for example WSDL_B, which uses the same schema as the WSDL document, for example WSDL_A, on which you have already run the wizard, the framework would have to generate Java classes based on WSDL_B that were already generated based on WSDL_A. When you run the wizard on WSDL_B, the framework can keep the “duplicate” Java classes from the previous execution of the wizard (based on WSDL_A, in our example) or override the “duplicate” Java classes with the ones from the current execution of the wizard (based on WSDL_B, in our example).

On the screen that opens, choose the existing files which you want to the framework to override with the ones from the current generation. The files that you leave deselected are kept from the previous execution of the wizard. Choose OK.

Using JAX-WS Customization Files

       1.      On the Service, Port, Binding names selection screen, proceed as follows:

                            a.      Specify names for the service, port and binding with which you want the Web service framework to update the WSDL document. You can accept the default values.

If the WSDL document you are using already contained binding information before you imported it, you cannot edit the name of the binding.

                            b.      Choose Next.

       2.      On the Customization files screen, choose Add to select the customization files.

       3.      Choose Next, and then choose Finish.

       4.      WSDL documents which use the same schema may use the same types. If you are running the wizard on a WSDL document, for example WSDL_B, which uses the same schema as the WSDL document, for example WSDL_A, on which you have already run the wizard, the framework would have to generate Java classes based on WSDL_B that were already generated based on WSDL_A. When you run the wizard on WSDL_B, the framework can keep the “duplicate” Java classes from the previous execution of the wizard (based on WSDL_A, in our example) or override the “duplicate” Java classes with the ones from the current execution of the wizard (based on WSDL_B, in our example).

On the screen that opens, choose the existing files which you want to the framework to override with the ones from the current generation. The files that you leave deselected are kept from the previous execution of the wizard. Choose OK.

Using No Customizations

       1.      On the Service, Port, Binding names selection screen, proceed as follows:

                            a.      Specify names for the service, port and binding with which the Web service framework will update the WSDL document. You can accept the default values.

If the WSDL document you are using already contained binding information before you imported it, you cannot edit the name of the binding.

                            b.      Choose Next.

       2.      Choose Finish.

       3.      WSDL documents which use the same schema may use the same types. If you are running the wizard on a WSDL document, for example WSDL_B, which uses the same schema as the WSDL document, for example WSDL_A, on which you have already run the wizard, the framework would have to generate Java classes based on WSDL_B that were already generated based on WSDL_A. When you run the wizard on WSDL_B, the framework can keep the “duplicate” Java classes from the previous execution of the wizard (based on WSDL_A, in our example) or override the “duplicate” Java classes with the ones from the current execution of the wizard (based on WSDL_B, in our example).

On the screen that opens, choose the existing files which you want to the framework to override with the ones from the current generation. The files that you leave deselected are kept from the previous execution of the wizard. Choose OK.

Result

●      The framework generates the service endpoint interface, reference classes and the service class in the output folder.

●      The class path is updated with additional JAR files.

Next Steps

       1.      Create the Web service client application. More information: Creating Web Service Client Applications

       2.      Deploy the Web service client on the application server (for deployable proxies only). More information: Building, Publishing and Removing Published Java EE Applications.

       3.      Configure the Web service client in the NetWeaver Administrator. More information: Configuring Web Services and Web Service Clients in the SAP NetWeaver Administrator.

When you deploy a Web service client which comprises a Web service proxy and a consumer application on the application server, you can configure that Web service client in the SAP NetWeaver Administrator (NWA). If you deploy only a Web service proxy without the corresponding consumer application on the application server, the NWA does not allow you to configure the deployed proxy. Moreover the deployed proxy is not displayed in the configuration applications of the NWA.