Avitek Medical Records Development Tutorials
This tutorial describes how to invoke the MedRecWebServices
WebLogic Web Service (contained in the medrecEar
application) that you created in Tutorial 11: Creating a J2EE Web Service by Programming a JWS File from the following types of client applications:
Stateless session EJBs and stand-alone Java clients use the client-side artifacts generated by the clientgen
Ant task to invoke a Web Service. The .NET client is written in C# and is provided to show that you can invoke a WebLogic Web Service from non-Java clients as well.
The clientgen
WebLogic Web Services Ant task generates, from an existing WSDL file, the client artifacts that client applications use to invoke both WebLogic and non-WebLogic Web Services. These artifacts include:
Note: You can use the clientgen
Ant task to generate the JAX-RPC stubs for Web Services deployed on both WebLogic Server and other application servers.
The tutorial includes the following sections:
It is assumed that you already know how to create a session EJB, a stand-alone Java Swing client application, and a .NET client application, and you want to learn how to update them to invoke a Web Service.
Before starting this tutorial, complete tutorials 5 through 11 to create the project directory and perform the intermediate build steps for the Physician and Medrec Applications.
If you skipped any of the tutorials 5 through 11, you can catch up by following these steps:
prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd
physicianEar
source directory and execute the ant
command to compiled its components:prompt> cd c:\medrec_tutorial\src\physicianEar
prompt> ant
Although this tutorial shows how to build a Web Service in the physicianEar
application, it is assumed that other components of physicianEar
, such as the value objects, have already been compiled, which is why this step is required.
medrecEar
source directory and execute the following ant
commands to first build medrecEar
(including its MedRecWebServices
service that you are going to invoke in this tutorial) and then deploy the application:prompt> cd c:\medrec_tutorial\src\medrecEar
prompt> ant
prompt> ant deploy.medrec.ear
Each of the following steps shows the code excerpt needed to invoke a Web Service from a different type of client application.
This procedure describes how to invoke a Web Service from the PhysicianSessionEJB
of the Physician application. The procedure shows you how to run the clientgen
Ant task to generate most of the needed Java code, and then walks you through the EJB code in the PhysicianSessionEJB
used to invoke the Web Service.
prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd
prompt> cd c:\medrec_tutorial\src\physicianEar
prompt> notepad my_webserv_client.xml
my_webserv_client.xml
file (substituting, if necessary, your actual MedRec project directory for c:\medrec_tutorial
).Note: If you do not want to create the build file manually, copy the contents of the ws_ejb_client_tutorial.xml
file to the new file, my_webserv_client.xml
. Then follow along to understand the file contents. In the ws_ejb_client_tutorial.xml
file, it is assumed that your MedRec project directory is c:\medrec_tutorial
.
<project name="EJB Web Service Invoke" default="build.ws.client">
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<target name="build.ws.client">
<clientgen
wsdl="http://localhost:7101/ws_medrec/MedRecWebServices?WSDL"
destDir="c:/medrec_tutorial/build/physicianEar/APP-INF/classes"
packageName="com.bea.medrec.webservices.client"
classpath="${java.class.path};c:/medrec_tutorial/build/physicianEar/APP-INF/lib/value.jar"/>
<delete includeEmptyDirs="true" failonerror="false" quiet="false">
<fileset dir="c:/medrec_tutorial/build/physicianEar/APP-INF/classes/com/bea/medrec/value"/>
</delete>
<javac
srcdir="c:/medrec_tutorial/build/physicianEar/APP-INF/classes/com"
includes="**/*.java"
classpath="${java.class.path};c:/medrec_tutorial/build/physicianEar/APP-INF/lib/value.jar;c:/medrec_tutorial/build/physicianEar/APP-INF/classes"/>
</target>
</project>
The Ant build file first uses the taskdef
task to specify the full classname of the clientgen
Ant task.
The Ant build file then calls the clientgen
Web Services Ant task which generates the client-side artifacts needed to invoke a Web Service. The wsdl
attribute specifies that the clientgen
Ant task use the WSDL of the WebLogic Web Service you deployed in Tutorial 11: Creating a J2EE Web Service by Programming a JWS File when generating the artifacts. The destdir
attribute specifies that clientgen
generate its artifacts into the APP-INF/classes
directory of the physicianEar
build directory. The APP-INF
directory is part of the WebLogic split development directory environment and is used to ensure that the generated classes are available to other modules, such as the PhysicianSessionEJB
, in the deployed application. The packageName
attribute specifies the package into which Java code is generated. Finally, the classpath
attribute updates the CLASSPATH with the value.jar JAR
file that contains the compiled value-classes of the user-defined data types, such as Patient
and Record
.
In this release of WebLogic Server, however, there is no way to tell the clientgen
Ant task not to generate Java representations of the user-defined data types in the WSDL file, or in other words, the same value-classes that already exist in the value.jar
file. The classes generated by clientgen
do not include additional methods added to the custom value classes that are required by the MedRec application. For this reason, you must execute the delete
task to delete the clientgen
-generated classes so that they are not inadvertently used by the MedRec application.
Because clientgen
generates uncompiled Java classes, the build file then calls the javac
task to compile all generated code.
Note: In the preceding Ant build file, it is assumed that the MedRecWebServices
WebLogic Web Service is deployed to WebLogic Server and its WSDL is accessible. This is the typical way you always run the clientgen
Ant task. However, if you have not yet deployed the Web Service, you can point the wsdl
attribute to a static WSDL file, in particular the one that was generated when you compiled the medrecEar
application that contains the MedRecWebServices
service. To use the static WSDL file, update the wsdl
attribute of the clientgen
task in my_webserv_client.xml
as shown:
<clientgen
wsdl="c:/medrec_tutorial/build/medrecEar/MedRecWebServices/WEB-INF/MedRecWebServices.wsdl
"
...
prompt> ant -f my_webserv_client.xml
The clientgen
Ant task shows output similar to the following:
Buildfile: my_webserv_client.xml
Trying to override old definition of task clientgen
build.ws.client:
[clientgen] Generating client from http://localhost:7101/ws_medrec/MedRecWebServices?WSDL ...
[clientgen] Getting partner link
[clientgen] Package name is com.bea.medrec.webservices.client
[clientgen] DestDir is C:\medrec_tutorial\build\physicianEar\APP-INF\classes
[clientgen] class name is MedRecWebServicesPortType_Stub
[clientgen] service class name is MedRecWebServices
[clientgen] Porttype name is MedRecWebServicesPortType
[clientgen] service impl name is MedRecWebServices_Impl
[delete] Deleting 8 files from C:\medrec_tutorial\build\physicianEar\APP-INF\classes\com\bea\medrec\value
[delete] Deleted 1 directory from C:\medrec_tutorial\build\physicianEar\APP-INF\classes\com\bea\medrec\value
[javac] Compiling 5 source files
[javac] Note: C:\medrec_tutorial\build\physicianEar\APP-INF\classes\com\bea\medrec\webservices\client\MedRecWebServicesPortType_Stub.java uses unchecked orunsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.
BUILD SUCCESSFUL
Total time: 7 seconds
Note: This part of the tutorial simply walks you through the EJB code you would write; the PhysicianSessionEJB.ejb
code in the medrecEar
application already contains the code needed to invoke the MedRecWebServices
Web Service.
prompt> cd c:\medrec_tutorial\src\physicianEar\physSessionEjbs\com\bea\medrec\controller
prompt> notepad PhysicianSessionEJB.ejb
getMedRecWebServicesPort()
. This method contains the standard Java code that creates a JAX-RPC port of the MedRecWebServices
Web Service, shown in bold:wsUrl = (String) initCtx.lookup("java:comp/env/webservice/url");
wsUsername = (String) initCtx.lookup("java:comp/env/webservice/username");
wsPassword = (String) initCtx.lookup("java:comp/env/webservice/password");
logger.debug("MedRec Web Service URL: " + wsUrl);MedRecWebServices service = new MedRecWebServices_Impl(wsUrl+"?WSDL");
port = service.getMedRecWebServicesPort(wsUsername, wsPassword);
The URL of the WSDL of the deployed MedRecWebServices
, as well as the user and password of the user that will invoke the Web Service, is defined using the @EnvEntries
EJBGen annotation at the beginning of the PhysicianSessionEJB.ejb
file. The actual URL is:
http://host:7101/ws_medrec/MedRecWebServices?WSDL
For information about compiling, see Tutorial 7: Compiling Split Development Directory Applications with Ant Tasks.
This procedure shows how to invoke a Web Service from a stand-alone Java Swing client application. The procedure first describes how to run the clientgen
Ant task to generate most of the needed Java code, and then walks you through the actual Java client code you need to write. It is assumed that you know how to write, compile, and run a Java Swing client application.
prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd
prompt> cd c:\medrec_tutorial\src\clients
prompt> notepad my_webserv_client.xml
my_webserv_client.xml
file (substituting, if necessary, your actual MedRec project directory for c:/medrec_tutorial
).Note: If you do not want to create the build file manually, copy the contents of the file ws_standalone_client_tutorial.xml
file to the new file, my_webserv_client.xml
. Then follow along to understand the file contents. It is assumed that your MedRec project directory is c:/medrec_tutorial
.
<project name="Standalone Web Service Invoke" default="build.ws.client" >
<taskdef name="clientgen"
classname="weblogic.wsee.tools.anttasks.ClientGenTask" />
<target name="build.ws.client">
<clientgen
wsdl="http://localhost:7101/ws_medrec/MedRecWebServices?WSDL"
destDir="c:/medrec_tutorial/build/swing_client/clientgen"
packageName="com.bea.medrec.webservices"/>
<javac
srcdir="c:/medrec_tutorial/build/swing_client/clientgen"
destdir="c:/medrec_tutorial/build/swing_client/wsclient"
includes="**/*.java"/>
<javac
srcdir="com"
destdir="c:/medrec_tutorial/build/swing_client/wsclient"
includes="**/*.java"
classpath="${java.class.path};c:/medrec_tutorial/build/swing_client/wsclient" />
</target>
</project>
The Ant build file first uses the taskdef
task to specify the full classname of the clientgen
Ant task.
The Ant build file then calls the clientgen
Web Services Ant task, which generates the client-side artifacts needed to invoke a Web Service. The wsdl
attribute specifies that the clientgen
Ant task use the WSDL of the WebLogic Web Service you deployed in Tutorial 11: Creating a J2EE Web Service by Programming a JWS File when generating the artifacts. The destdir
attribute specifies that clientgen
generate its artifacts into the c:/medrec_tutorial/build/swing_client/clientgen
directory. The packageName
attribute specifies the package into which Java code is generated.
Because clientgen
generates uncompiled Java classes, the build file then calls the javac
task to compile all generated code. The second javac
task compiles the Swing client itself (whose source code is located in c:\medrec_tutorial\src\clients\com
) into the same directory into which the clientgen
-generated Java code was compiled.
Note: In the preceding Ant build file, it is assumed that the MedRecWebServices
WebLogic Web Service is deployed to WebLogic Server and its WSDL is accessible. This is the typical way you run the clientgen
Ant task. However, if you have not yet deployed the Web Service, you can point the wsdl
attribute to a static WSDL file, in particular the one that was generated when you compiled the medrecEar
application that contains the MedRecWebServices
service. To use the static WSDL file, update the wsdl
attribute of the clientgen
task in my_webserv_client.xml
as shown:
<clientgen
wsdl="c:/medrec_tutorial/build/medrecEar/MedRecWebServices/WEB-INF/MedRecWebServices.wsdl
"
...
prompt> ant -f my_webserv_client.xml
The clientgen
Ant task shows the following output:
Buildfile: my_webserv_client.xml
Trying to override old definition of task clientgen
build.ws.client:
[clientgen] Generating client from http://localhost:7101/ws_medrec/MedRecWebServices?WSDL ...
[clientgen] Getting partner link
[clientgen] Package name is com.bea.medrec.webservices
[clientgen] DestDir is C:\medrec_tutorial\build\swing_client\clientgen
[clientgen] class name is MedRecWebServicesPortType_Stub
[clientgen] service class name is MedRecWebServices
[clientgen] Porttype name is MedRecWebServicesPortType
[clientgen] service impl name is MedRecWebServices_Impl
[javac] Compiling 13 source files to C:\medrec_tutorial\build\swing_client\wsclient
[javac] Note: C:\medrec_tutorial\build\swing_client\clientgen\com\bea\medrec\webservices\MedRecWebServicesPortType_Stub.java uses unchecked or unsafe operat
ions.
[javac] Note: Recompile with -Xlint:unchecked for details.
[javac] Compiling 4 source files to C:\medrec_tutorial\build\swing_client\wsclient
BUILD SUCCESSFUL
Total time: 8 seconds
Note: This part of the tutorial simply walks you through the Java code you would write; the Java Swing client application of the MedRec tutorial JAR file already contains the code needed to invoke the MedRecWebServices
Web Service.
prompt> cd c:\medrec_tutorial\src\clients\com\bea\medrec\webservices\swing
prompt> notepad EditProfileFrame.java
submitButton_actionPerformed(ActionEvent e)
which returns patient information, based on the patient's Social Security number, when a user of the application clicks Submit. This method contains the following Java code:MedRecWebServices ws =
new MedRecWebServices_Impl(this.WSDLTextField.getText());
MedRecWebServicesPortType port = ws.getMedRecWebServicesPort();
Patient Patient =
(Patient)port.findPatientBySsn(this.patientIDTextField.getText());
The preceding code shows how to create a JAX-RPC stub of the MedRecWebServices
Web Service from the WSDL in the WSDLTextField
of the application, and then invoke the findPatientBySsn
Web Service operation.
saveButton_actionPerformed(ActionEvent e)
, which saves updated patient information to the MedRec application by invoking the updatePatient
Web Service operation on the JAX-RPC stub port
, created in the preceding step:port.updatePatient(patient);
prompt> cd c:\medrec_tutorial\src\clients
prompt> ant -f build.xml run
You can also invoke the MedRecWebServices
WebLogic Web Service from a .NET client application written in C#.
You must install the .NET Framework (Version 1.1) on your computer before you can create and run the C# client. See Microsoft .NET Framework Development Center.
The sample C# client that invokes the MedRecWebServices
WebLogic Web Service is in the following directory:
prompt> c:\medrec_tutorial\src\clients\CSharpClient
To run the client, either rebuild it using the .NET IDE, or execute the following already-built application:
prompt> c:\medrec_tutorial\src\clients\CSharpClient\bin\Release\CSharpClient.exe
The already-built client is hard-coded to invoke the MedRecWebService
deployed at http://localhost:7001
, so be sure to update the wsdl location field of the client with the host and port number of your own MedRecServer.
clientgen
Ant task to generate almost all the required client-side artifacts, such as the JAX-RPC stubs. clientgen
, you must compile the generated Java code into class files. APP-INF/classes
directory of the application so that all modules of the application can access the classes. It is assumed, of course, that you are using the WebLogic split development directory environment.wsdl
attribute of clientgen
to generate the client-side artifacts from the WSDL, or public contract, of a Web Service.
Client applications that invoke Web Services can be written using any technology: Java, Microsoft SOAP Toolkit, Microsoft .NET, and so on. Java client applications use the Java API for XML-Based RPC (JAX-RPC), a Sun Microsystems specification that defines the Java client API for invoking a Web Service. A Java client application can be an EJB deployed on WebLogic Server, or a stand-alone Java client.
In Tutorial 11: Creating a J2EE Web Service by Programming a JWS File, you learned how to create and deploy the MedRecWebServices
Web Service (part of the main MedRec application), which contains operations to find and update patient information, such as updatePatient
and findPatientBySsn
. The public contract of the Web Service is published via its WSDL, which lists its operations, the URL endpoints, and so on.
The Physician application, in a real-life situation, would be deployed on a separate WebLogic Server instance from the main MedRec application. The PhysicianSessionEJB
, therefore, needs a way to communicate with the MedRec application over the Internet; using the operations of the MedRecWebServices
Web Service is the ideal way to do this. The client-side artifacts generated by the clientgen
Ant task contains the JAX-RPC stubs needed to invoke the Web Service operations—the amount of code you need to actually write in the EJB is very small.
The stand-alone Java client works essentially the same way as the EJB as far as using the artifacts generated by clientgen
.