Avitek Medical Records Development Tutorials
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.
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.
To implement the MedRecWebServices
service:
prompt> cd C:\medrec_tutorial\src\medrecEar\webServices\com\bea\medrec\webservices
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.
@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.
After you program the JWS file, you use the jwsc
Ant task to generate a deployable Web Service.
prompt> cd c:\medrec_tutorial\src\medrecEar
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
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.
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:
prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd
prompt> cd c:\medrec_tutorial\src\medrecEar
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
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
).
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.
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
prompt> c:\bea
\weblogic91\common\eval\pointbase\tools\
startPointBase.cmd
prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd
prompt> cd c:\medrec_tutorial\src\medrecEar
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.
http://
host
:7101/ws_medrec/MedRecWebServices?WSDL
@SOAPBinding
annotation to specify the type of Web Service. Document-literal-wrapped is the default.jwsc
Ant task to generate all required Web Service artifacts from a JWS file.
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.