Developing the MedRec Applications

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.

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.

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.

Procedure

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

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

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:

@javax.jws.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")

@javax.jws.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)

@weblogic.jws.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")

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

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.

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

prompt> cd c:\medrec_tutorial\src\medrecEar

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

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 <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:

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

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

Move to the medrecEar directory:

prompt> cd c:\medrec_tutorial\src\medrecEar

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] JWS: processing module /MedRecWebServices
     [jwsc] Parsing source files
     [jwsc] Parsing source files
     [jwsc] 1 JWS files being processed for module /MedRecWebServices
     [jwsc] JWS: C:\medrec_tutorial\src\medrecEar\webServices\com\bea\medrec\webservices\MedRecWebServices.java Validated.
     [jwsc] Compiling 2 source files to C:\WINDOWS\TEMP\_40m0yp
     [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] Copying 2 files to C:\medrec_tutorial\build\medrecEar\MedRecWebServices
     [jwsc] [EarFile] Application File : C:\medrec_tutorial\src\medrecEar\META-INF\application.xml
[AntUtil.deleteDir] Deleting directory C:\WINDOWS\TEMP\_40m0yp

BUILD SUCCESSFUL
Total time: 16 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:

The com/bea/medrec/webservices/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.

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

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

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

Open another command shell and set your environment:

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

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

prompt> cd c:\medrec_tutorial\src\medrecEar

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@MedRecAppScoped JMS@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] <Apr 5, 2007 2:26:18 PM PDT> <Info> <J2EE Deployment SPI> <BEA-260121> <Initiating deploy operation for application, MedRecEAR [archive: C:\medrec_tutorial\build\medrecEar], to MedRecServer MedRecJMSServer .>
 [wldeploy] Task 9 initiated: [Deployer:149026]deploy application MedRecEAR on MedRecJMSServer,MedRecServer.
 [wldeploy] Task 9 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: 34 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:

<Apr 4, 2007 1:14:15 PM PDT> <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\physicianEar\deploy.xml:8: 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.

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

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:

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.

Avitek Medical Records Development Tutorials