Creating Outside-In Web Services 

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 a Web service using a WSDL document as a basis.

In this case, the Web service framework generates the skeleton of the implementation bean containing the Web service methods’ declarations for the operations in the WSDL document. You have to provide your own implementation to the Web service methods.

The Web service framework generates outside-in Web services with EJB endpoints only. By default, the framework creates a stateless session EJB for an endpoint.

 

Once the skeleton of the implementation bean is generated, you can change the stateless EJB to stateful by replacing the @Stateless annotation with @Stateful in the generated skeleton of the implementation bean.

As a basis for the outside-in Web service generation, 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. During the Web service generation, the framework updates the WSDL document with the necessary information. By default, when 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.

Collision Resolution and Global Customizations

When generating outside-in Web services, collisions may arise in the mapping between names in the WSDL and the names of the corresponding Java artifacts. For example, long names in the WSDL document may result in long names of Java classes.

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

●      You can use customization options integrated in the wizard for creating outside-in Web services. 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

●      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.

●      An enterprise application project is created. The EJB 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. In this case you can start the wizard directly from the Enterprise Service browser. More information: Browsing Enterprise Services from the SAP NetWeaver Developer Studio.

●      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 create a Web service. More information: Importing WSDL Documents in the SAP NetWeaver Developer Studio.

 

If you want to create a Web service from 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.      To create a Web service from a WSDL document you imported, in the Project Explorer of the J2EE perspective, choose the WSDL document, and then from the context menu choose Web Services à Generate Java bean skeleton.

If you want to create a Web service from 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 Java bean skeleton. 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) and you can provide an implementation of the generated Java bean skeleton.

                            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 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 endpoint interface (SEI), and fault(s). The Java class for the SEI has the name of the WSDL portType and is generated based on the WSDL portType and binding.

The Bean class which implements the SEI is generated in this same package.

 

If the WSDL document imports other WSDL documents, only one package is generated with 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 appears when very long Java class names would be generated or when there are still unresolved collisions. 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 endpoint interface (SEI), and fault(s). The Java class for the SEI has the name of the WSDL portType and is generated based on the WSDL portType and binding.

The Bean class which implements the SEI is generated in this same package.

If the WSDL document imports other WSDL documents, only one package is generated and 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 implementation bean is generated. For every property of a design time feature (such as authentication level or WSRM enablement) that is configured in the WSDL document, the Web service framework has generated the corresponding design time annotations.

Next steps:

       1.      Provide implementation to the business methods of the Web service.

       2.      When you implement the Web service, you can configure the properties of design time or runtime features for this Web service by using annotations provided by SAP. More information: Configuring Web Services at Design Time.

If you want to provide a WS-RM-enabled Web service, or a Web service which uses TU&C/C, in the application-j2ee-engine.xml file of the EAR containing the Web service, add a runtime reference to the WS-RM application on the application server as shown in the code sample below:

<?xml version="1.0" encoding="UTF-8"?> <application-j2ee-engine xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="application-j2ee-engine.xsd">   <reference reference-type="hard">     <reference-target target-type="application" provider-name="sap.com">tc~esi~esp~wsrm~app</reference-target>   </reference> </application-j2ee-engine>

       3.      Deploy the implemented Web service. More information: Building, Publishing and Removing Published Java EE Applications.

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