Skip navigation.
Downloads | Product Documentation | Support

Avitek Medical Records Development Tutorials

# Developing the MedRec Applications

# Tutorial 11: Creating a J2EE Web Service by Programming a JWS File

This tutorial describes how to create a J2EE Web Service, as specified by the Enterprise Web Services 1.1 specification (JSR-921).

The tutorial first looks at the Java Web Service (JWS) file that implements the Web Service, and then shows how to use `jwsc`, the WebLogic Web Service Ant task, to automatically generate all the supporting artifacts that make up the Web Service. The tutorial then shows how to deploy the Web Service and view its WSDL file. Tutorial 12: Invoking a Web Service from a Client Application describes how Web Services can be invoked by a variety of client applications using SOAP.

A JWS file is an ordinary Java class file that uses JDK 5.0 metadata annotations to specify the shape and characteristics of the Web Service. The JWS annotations you can use in a JWS file include the standard ones defined by the Web Services Metadata for the Java Platform specification (JSR-181) as well as a set of WebLogic-specific ones.

After you program the JWS file, you use the `jwsc` WebLogic Web Service Ant task to compile the JWS file into either a Java class or a stateless session EJB, as described by the Enterprise Web Services 1.1 specification. You typically do not need to decide this backend implementation of the Web Service; the `jwsc` Ant task picks the optimal implementation based on the JWS annotations you have specified in the JWS file. The `jwsc` Ant task also generates all the supporting artifacts for the Web Service (deployment descriptors, XML Schema representation of Java user-defined data types, WSDL file), packages everything into an archive file, and creates an Enterprise Application that you can then deploy to WebLogic Server.

The tutorial includes:

- Prerequisites
- Procedure
- Best Practices
- The Big Picture
- Related Reading

# Prerequisites

Previous tutorials work exclusively with the Physician application, `physicianEar`. This tutorial uses the main MedRec application, `medrecEar`, which contains a variety of Web Services in the `webServices` subdirectory. This tutorial describes how to program the `MedRecWebServices` service, whose JWS file is located in the `C:\medrec_tutorial\src\medrecEar\webServices\com\bea\medrec\webservices` directory. This Web Service provides public operations for the main MedRec services, such as retrieving information about a patient or a particular visit, or updating a patient's profile.

Before starting this tutorial, create the project directory and copy over the source files and output directories using the instructions in Tutorial 5: Creating the MedRec Project Directory.

# Procedure

To implement the `MedRecWebServices` service:

- Step 1: View the MedRecWebServices.java JWS file that implements the Web Service.
- Step 2: Create the build file that contains the call to the jwsc Ant task.
- Step 3: Execute the jwsc Ant task to generate the Web Service.
- Step 4: View the generated Web Service artifacts.
- Step 5: Deploy the Web Service and view its WSDL.

## Step 1: View the MedRecWebServices.java JWS file that implements the Web Service.

1. Open a command window and move to the directory that contains the MedRecWebServices.java JWS file that implements the MedRecWebServices service:

>     prompt> cd C:\medrec_tutorial\src\medrecEar\webServices\com\bea\medrec\webservices

2. Use an IDE or text editor to view the `MedRecWebServices.java` file:

>     prompt> notepad MedRecWebServices.java

The `MedRecWebServices.java` JWS file is a Java file that contains JWS annotations, both standard and WebLogic-specific, that describe the Web Service-specific shape and behavior of the service. The methods of the Java file contain the business logic that implements the public operations of the Web Service; these methods include `getRecord` that returns the record of a patient based on a record ID and `findPatientBySsn` that returns patient information based on the patient's Social Security number.

The JWS annotations used in `MedRecWebServices.java` include:

- `@WebService`—Standard class-level annotation that specifies the name of the Web Service, both internal and as it appears in the WSDL file, and the target name space used in the WSDL:

>     @WebService(name = "MedRecWebServicesPortType",
>         serviceName = "MedRecWebServices",
>         targetNamespace = "http://www.bea.com/medrec")

- `@SOAPBinding`—Standard class-level annotations that specifies the type of Web Service, such as document-literal-wrapped (shown in example) or rpc-encoded:

>     @SOAPBinding(style=SOAPBinding.Style.DOCUMENT,
>                  use=SOAPBinding.Use.LITERAL,
>                  parameterStyle=SOAPBinding.ParameterStyle.WRAPPED)

- `@WLHttpTransport`—WebLogic-specific class-level annotation that specifies the name of the port in the WSDL file and the URI used to invoke the Web Service:

>     @WLHttpTransport(portName = "MedRecWebServicesPort",
>         contextPath = "ws_medrec",
>         serviceUri = "MedRecWebServices")

- `@WebMethod`—Standard method-level annotation that specifies which methods of the JWS file will be exposed as public operations of the Web Service.

See Programming the JWS File for detailed information about creating a JWS file and JWS Annotations Reference for the full list of JWS annotations you can use in a JWS file.

## Step 2: Create the build file that contains the call to the jwsc Ant task.

After you program the JWS file, you use the `jwsc` Ant task to generate a deployable Web Service.

1. Open a command window and change to the `medrecEar` subdirectory in the MedRec project directory:

>     prompt> cd c:\medrec_tutorial\src\medrecEar

2. Use a text editor to create a file called `my_webserv.xml` file in the `medrecEar` directory:

>     prompt> notepad my_webserv.xml

Note: If you do not want to enter the build file manually, copy the file `webservices_tutorial.xml` file to the new file name, `my_webserv.xml`. Then follow along to understand the file contents. The`webservices_tutorial.xml` file treats `c:/medrec_tutorial` as your MedRec project directory

3. Add the following lines to the `my_webserv.xml` file (substituting, if necessary, your actual MedRec project directory for `c:/medrec_tutorial`); the Ant tasks are described at the end of this step:

>     <project name="WebServicesTutorial" default="build.ws">

>       <path id="jwsc.class.path">

>         <pathelement path="${java.class.path}"/>
>         <pathelement path="c:/medrec_tutorial/build/medrecEar/sessionEjbs"/>
>         <pathelement path="c:/medrec_tutorial/build/medrecEar/APP-INF/lib/value.jar" />
>         <pathelement path="c:/medrec_tutorial/build/medrecEar/APP-INF/lib/utils.jar" />
>         <pathelement path="c:/medrec_tutorial/build/medrecEar/APP-INF/lib/log4j.jar" />

>       </path>

>       <taskdef name="jwsc" classname="weblogic.wsee.tools.anttasks.JwscTask" />

>       <target name="build.ws">

>         <jwsc
>           srcdir="webServices/com/bea/medrec/webservices"
>           sourcepath="webServices"
>           destdir="c:/medrec_tutorial/build/medrecEar"
>           applicationXml="c:/medrec_tutorial/src/medrecEar/META-INF/application.xml"
>         >
>           <classpath refid="jwsc.class.path" />
>           <jws file="MedRecWebServices.java" explode="true"/>

>         </jwsc>

>       </target>

>     </project>

The `<path>` element is used to create a structure, called `jwsc.class.path`, that contains a list of directories and JAR files that will later be added to the CLASSPATH of the `jwsc` Ant task when it compiles the JWS file.

The `<taskdef>` task identifies the full classname of the `jwsc` Ant task.

The `<jwsc>` Ant task uses the following attributes:

- `srcdir`—Full pathname of the top-level directory that contains the MedRecWebServices.java JWS file.
- `sourcepath`—Full pathname of the top-level directory that contains the Java files referenced by the JWS file, such as JavaBeans used as parameters or user-defined exceptions.
- `destdir`—Full pathname of the directory that will contain the compiled JWS files, XML Schemas, WSDL, and generated deployment descriptor files.
- `applicationXml`—Full name and path of the `application.xml` deployment descriptor of the Enterprise Application.

The `<classpath>` child element of `<jwsc>` adds to its CLASSPATH the directories and JAR files previously specified with the `<path>` element. The `<jws>` child element specifies the name of the JWS file to be compiled and that the generated components should be in exploded format, rather than archived in a WAR or JAR file.

## Step 3: Execute the jwsc Ant task to generate the Web Service.

After you create the `my_webserv.xml` file, use it to execute the `jwsc` Ant task to generate the Web Service artifacts based on the `MedRecWebServices.java` JWS file:

1. Open a commend window and set your environment using the `MedRecDomain` environment script:

>     prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd

2. Move to the `medrecEar` directory:

>     prompt> cd c:\medrec_tutorial\src\medrecEar

3. Execute the Web Service Ant tasks by running the `my_webserv.xml` script using the `ant` command:

>     prompt> ant -f my_webserv.xml

The `jwsc` Ant task produces output similar to the following to show its progress:

>     Buildfile: my_webserv.xml

>     build.ws:
>          [jwsc] 1 JWS files will be processed.
>          [jwsc] Processing JWS: C:\medrec_tutorial\src\medrecEar\webServices\com\bea\medrec\webservices\MedRecWebServices.java
>          [jwsc] JWS: C:\medrec_tutorial\src\medrecEar\webServices\com\bea\medrec\webservices\MedRecWebServices.java Validated.
>          [jwsc] Compiling 2 source files to C:\WINDOWS\TEMP\_ptaghb
>          [jwsc] Copying 1 file to C:\medrec_tutorial\build\medrecEar\MedRecWebServices\WEB-INF
>          [jwsc] Copying 9 files to C:\medrec_tutorial\build\medrecEar\MedRecWebServices\WEB-INF
>          [jwsc] Copying 4 files to C:\medrec_tutorial\build\medrecEar\MedRecWebServices\WEB-INF\classes
>          [jwsc] Created JWS deployment directory: C:\medrec_tutorial\build\medrecEar\MedRecWebServices
>     [AntUtil.deleteDir] Deleting directory C:\WINDOWS\TEMP\_ptaghb

>     BUILD SUCCESSFUL
>     Total time: 8 seconds

If you did not receive the preceding output, or ran into a problem, you can use the Ant build file provided for this tutorial instead:

>     prompt> ant -f webservices_tutorial.xml

## Step 4: View the generated Web Service artifacts.

Although you should never update the artifacts generated by the `jwsc` Ant task, it is sometimes useful to view them so as to understand what makes up a deployable Web Service.

Move to the build directory into which the `jwsc` Ant task generated the `MedRecWebServices` artifacts:

>     prompt> cd c:\medrec_tutorial\build\medrecEar\MedRecWebServices

The `MedRecWebServicesPortType.java` file is the generated endpoint service interface file; its contents are based on the methods of the JWS file that will be exposed as public operations of the Web Service.

The `WEB-INF` subdirectory contains the generated deployment descriptors, such as `webservices.xml` and `weblogic-webservices.xml`, and the generated WSDL file `MedRecWebServices.wsdl`. Because this Web Service will be packaged into a Web application archive, this directory also contains corresponding descriptors: `web.xml` and `weblogic.xml`. The `WEB-INF\classes` subdirectory contains the compiled Web Service classes, compiled either from the JWS file or from generated Java files (such as the service endpoint interface `MedRecWebServicesPortType.java`).

## Step 5: Deploy the Web Service and view its WSDL.

In this section, you deploy the entire MedRec application, which includes the `MedRecWebServices` Web Service, in the same way that you deployed the Physician application in Tutorial 9: Deploying MedRec from the Development Environment. In this tutorial, however, you use the deploy target of the existing `build.xml` file in the `medrecEar` directory rather than creating a new one.

Once the Web Service is deployed, you can view its WSDL file.

1. Start `MedRecServer`, if it is not already running, by executing its start script from a command window:

>     prompt> c:\bea\user_projects\domains\MedRecDomain\startweblogic.cmd

2. Start PointBase, if it is not already running, by executing its start script from another command window:

>     prompt> c:\bea\weblogic91\common\eval\pointbase\tools\startPointBase.cmd

3. Open another command shell and set your environment:

>     prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd

4. Move to the `medrecEar` subdirectory if you are not already there:

>     prompt> cd c:\medrec_tutorial\src\medrecEar

5. Enter the following command to execute the `deploy.medrec.ear` target of the existing `build.xml` file:

>     prompt> ant deploy.medrec.ear

You should receive the following output from the `wldeploy` task:

>     Buildfile: build.xml

>     deploy.medrec.ear:

>      [wldeploy] weblogic.Deployer -noexit -name MedRecEAR -source C:\medrec_tutorial\build\medrecEar -targets MedRecServer -adminurl t3://localhost:7101 -user weblogic -password ******** -deploy -submoduletargets MedRecJMSServer@MedRecAppScopedJMS@MedRecJMSServer -securityModel CustomRolesAndPolicies
>      [wldeploy] weblogic.Deployer invoked with options:  -noexit -name MedRecEAR -source C:\medrec_tutorial\build\medrecEar -targets MedRecServer -adminurl t3://localhost:7101 -user weblogic -deploy -submoduletargets MedRecJMSServer@MedRecAppScopedJMS@MedRecJMSServer -securityModel CustomRolesAndPolicies
>      [wldeploy] <Dec 9, 2005 3:54:33 PM PST> <Info> <J2EE Deployment SPI> <BEA-260121> <Initiating deploy operation for application, MedRecEAR [archive: C:\medrec_tutorial\build\medrecEar], to MedRecServer MedRecJMSServer .>
>      [wldeploy] Task 0 initiated: [Deployer:149026]deploy application MedRecEAR on MedRecJMSServer,MedRecServer.
>      [wldeploy] Task 0 completed: [Deployer:149026]deploy application MedRecEAR on MedRecJMSServer,MedRecServer.
>      [wldeploy] Target state: deploy completed on JMS Server MedRecJMSServer
>      [wldeploy] Target state: deploy completed on Server MedRecServer
>      [wldeploy]

>     BUILD SUCCESSFUL

>     Total time: 20 seconds

If you do not receive the preceding output, MedRecServer may not have finished starting up, in which case wait until you see the following status in the command window from which you started the server and then rerun the deploy task:

>     <Dec 9, 2005 10:52:20 AM PST> <Notice> <WebLogicServer> <BEA-000360> <Server started in RUNNING mode>

If you receive the following error when trying to deploy `medrecEar`, you might have forgotten to release the configuration when previously using the Administration Console:

>     BUILD FAILED

>     C:\medrec_tutorial\src\medrecEar\build.xml:256: weblogic.management.ManagementException: [Deployer:149163]The domain edit lock is owned by another session in non-exclusive mode - this deployment operation requires exclusive access to the edit lock and hence cannot proceed.

In this case be sure you click either Activate Changes or Release Configuration in the Change Center of the Administration Console and then rerun the deploy task.

6. To verify that the Web Service deployed, open a new browser window and enter the URL for the Web Service's WSDL:

>     http://host:7101/ws_medrec/MedRecWebServices?WSDL

where `host` refers to the computer on which MedRecServer is running. If your browser is on the same computer as MedRecServer, then you can use the URL:

>     http://localhost:7101/ws_medrec/MedRecWebServices?WSDL

# Best Practices

- Use JWS files to program a WebLogic Web Service. JWS files use JWS annotations, both standard and WebLogic-specific, to describe the shape and behavior of the Web Service. JWS annotations are based on the new JDK 5.0 metadata annotations feature. With this feature, most Web Service information is contained within the JWS file; supporting artifacts such as deployment descriptors and WSDL files are generated by Ant tasks.
- In general, document-literal-wrapped Web Services are the most interoperable type of Web Service. Use the `@SOAPBinding` annotation to specify the type of Web Service. Document-literal-wrapped is the default.
- Use the `jwsc` Ant task to generate all required Web Service artifacts from a JWS file.

# The Big Picture

The `com.bea.medrec.webservices.MedRecWebServices` JWS file of the MedRec application contains methods to view and update patient and record information, such as `getRecord()`, `findPatientByLastName()`, `updatePatient()` and so on. The methods of the JWS file that will be exposed as public operations are annotated with the `@WebMethod` annotation. These methods do not actually perform any of the business logic; rather, they call the existing session EJBs (such as `com.bea.medrec.controller.PatientSession` and `com.bea.medrec.controller.RecordSession`) to do the real work of viewing and searching for the patient and record information. You can think of the `MedRecWebServices` Web Service as a facade that takes incoming requests to the MedRec application and hands them off to the other session and entity EJBs that do the actual work.

The methods of the `MedRecWebServices` JWS file use the following user-defined Java data types as parameters and return values:

- `com.bea.medrec.value.Patient`
- `com.bea.medrec.value.Record`
- `com.bea.medrec.value.RecordsSummary`

Because clients invoke Web Services using SOAP, which uses XML files over the wire to transmit information, these Java data types must also have a corresponding XML Schema data type which the Web Services runtime uses when converting patient and record data between its Java and XML representations. The `jwsc` Ant task, when compiling the JWS file, also automatically generates XML Schemas types of these Java data types. See the `<types>` element in the generated WSDL file to view the XML Schema types.

Once the `MedRecWebServices` Web Service is deployed, all kinds of different client applications, from EJBs running on a different WebLogic Server instance to a .NET client, can easily get to and update the patient and record information managed by the MedRec application using the operations of the Web Service. The client applications use SOAP to invoke a Web Service operation, and WebLogic Server in turn uses SOAP to send the information back to the client.

# Related Reading

- Iterative Development of WebLogic Web Services Starting From Java: Main Steps in Programming Web Services for WebLogic Server
- Programming the JWS File in Programming Web Services for WebLogic Server
- JWS Annotation Reference in Programming Web Services for WebLogic Server
- jwsc Ant Task Reference in Programming Web Services for WebLogic Server
- Apache Ant in Developing Applications with WebLogic Server
- Web Services Metadata for the Java Platform (JSR-181) Specification
- Enterprise Web Services 1.1 Specification
- Web Services Description Language (WSDL) 1.1 Specification