3 Using the Development and Administration Tools

Oracle introduces you to the tools available for developing and administering WebLogic web services, such as Oracle IDEs to develop web services, administration tools to manage, test, and monitor WebLogic Web services, Oracle WebLogic Scripting Tool, Java Management Extensions (JMX), and so on.

Using Oracle IDEs to Develop Web Services

Oracle JDeveloper and Oracle Enterprise Pack for Eclipse (OEPE) tools are available to develop web services.

Oracle JDeveloper—Oracle's full-featured Java IDE, can be used for end-to-end development of web services. Developers can build Java classes or EJBs, expose them as web services, automatically deploy them to an instance of Oracle WebLogic Server, and immediately test the running web service. Alternatively, JDeveloper can be used to drive the creation of web services from WSDL descriptions. JDeveloper also is Ant-aware. You can use this tool to build and run Ant scripts for assembling the client and for assembling and deploying the service. See the Developing and Securing Web Services in Developing Applications with Oracle JDeveloper.
Oracle Enterprise Pack for Eclipse (OEPE)—Provides a collection of plug-ins to the Eclipse IDE platform that facilitate development of WebLogic web services. For more information, see the Eclipse IDE platform online help.

Using the Administration Tools to Manage, Test, and Monitor WebLogic Web Services

Basic administration of web services is very similar to basic administration of standard Java Platform, Enterprise Edition (Java EE) Version 5 applications and modules. These standard tasks include deploying and monitoring the Enterprise application, configuring the policy files, and so on.

When you use the jwsc Ant task to compile and package a WebLogic web service, the task packages it as part of an Enterprise application. The web service itself is packaged inside the Enterprise application as a Web application WAR file, by default. However, if your JWS file implements a session bean then the web service is packaged as an EJB JAR file.

The standard tasks include:

Deploying the Enterprise application that contains the web service.
Starting and stopping the deployed Enterprise application.
Configuring the Enterprise application and the archive file which implements the actual web service. You can configure general characteristics of the Enterprise application, such as the deployment order, or module-specific characteristics, such as session time-out for Web applications or transaction type for EJBs.
Creating and updating the Enterprise application's deployment plan.
Monitoring the Enterprise application.
Testing the Enterprise application.

The following provides examples of administrative tasks are specific to web services:

Configuring the policy files associated with a web service endpoint or its operations.
Viewing the SOAP handlers associated with the web service.
Viewing the WSDL of the web service.
Creating a web service security configuration.

There are a variety of ways to administer Java EE modules and applications that run on WebLogic Server, including web services, as described in the following sections:

Using Oracle Enterprise Manager Fusion Middleware Control

The Oracle Enterprise Manager Fusion Middleware Control (Fusion Middleware Control) is a Web browser-based, graphical user interface that you can use to administer and monitor a farm.

A farm is a collection of managed components. It can contain Oracle WebLogic Server domains, one or more Managed Servers and the Oracle Fusion Middleware system components that are installed, configured, and running in the domain.

Fusion Middleware Control organizes a wide variety of performance data and administrative functions into distinct, Web-based home pages for the farm, Oracle WebLogic Server domain, components, and applications. The Fusion Middleware Control home pages make it easy to locate the most important monitoring data and the most commonly used administrative functions—all from your Web browser.

For more information about managing, testing, and monitoring web services using the Enterprise Manager, see Administering Web Services.

Fusion Middleware Control is available as part of the Oracle Fusion Middleware product; it is not available to you if you purchase the standalone version of Oracle WebLogic Server. See Getting Started Using Oracle Enterprise Manager Fusion Middleware Control in Administering Oracle Fusion Middleware.

Using Oracle WebLogic Server Administration Console

The WebLogic Server Administration Console is a Web browser-based, graphical user interface you use to manage a WebLogic Server domain, one or more WebLogic Server instances, clusters, and applications, including web services, that are deployed to the server or cluster.

One instance of WebLogic Server in each domain is configured as an Administration Server. The Administration Server provides a central point for managing a WebLogic Server domain. All other WebLogic Server instances in a domain are called Managed Servers. In a domain with only a single WebLogic Server instance, that server functions both as Administration Server and Managed Server. The Administration Server hosts the WebLogic Server Administration Console, which is a Web Application accessible from any supported Web browser with network access to the Administration Server.

You can use the WebLogic Server Administration Console to:

For more information about using the WebLogic Server Administration Console to administer web services, see the Web Services.

The following sections provide more details on the following topics:

Invoking the Administration Console

To invoke the WebLogic Server Administration Console in your browser, enter the following URL:

http://host:port/console

where

host refers to the computer on which the Administration Server is running.
port refers to the port number where the Administration Server is listening for connection requests. The default port number for the Administration server is 7001.

Click the Help button, located at the top right corner of the WebLogic Server Administration Console, to invoke the Online Help for detailed instructions on using the WebLogic Server Administration Console.

How Web Services Are Displayed In the Administration Console

Web services are typically deployed to WebLogic Server as part of an Enterprise Application. The Enterprise Application can be either archived as an EAR, or be in exploded directory format. The web service itself is almost always packaged as a Web Application; the only exception is if your JWS file implements a session bean in which case it is packaged as an EJB. The web service can be in archived format (WAR or EJB JAR file, respectively) or as an exploded directory.

It is not required that a web service be installed as part of an Enterprise application; it can be installed as just the Web Application or EJB. However, Oracle recommends that users install the web service as part of an Enterprise application. The WebLogic Ant task used to create a web service, jwsc, always packages the generated web service into an Enterprise application.

To view and update the web service-specific configuration information about a web service using the WebLogic Server Administration Console, click on the Deployments node in the left pane and, in the Deployments table that appears in the right pane, locate the Enterprise application in which the web service is packaged. Expand the application by clicking the + node; the web services in the application are listed under the Web Services category. Click on the name of the web service to view or update its configuration.

The following figure shows how the HelloWorldService web service, packaged inside the helloWorldEar Enterprise application, is displayed in the Deployments table of the WebLogic Server Administration Console.

Figure 3-1 WebLogic Server Administration Console Main Window

Description of "Figure 3-1 WebLogic Server Administration Console Main Window"

Creating a Web Services Security Configuration

When a deployed WebLogic web service has been configured to use message-level security (encryption and digital signatures, as described by the WS-Security specification), the web services runtime determines whether a web service security configuration is also associated with the service. This security configuration specifies information such as whether to use an X.509 certificate for identity, whether to use password digests, the keystore to be used for encryption, and so on. A single security configuration can be associated with many web services.

Because web services security configurations are domain-wide, you create them from the domainName > WebService Security tab of the WebLogic Server Administration Console, rather than the Deployments tab. The following figure shows the location of this tab.

Figure 3-2 Web Service Security Configuration in Administration Console

Description of "Figure 3-2 Web Service Security Configuration in Administration Console"

Using the Oracle WebLogic Scripting Tool

The WebLogic Scripting Tool (WLST) is a command-line scripting interface that you can use to interact with and configure WebLogic Server domains and instances, as well as deploy Java EE modules and applications (including web services) to a particular WebLogic Server instance. Using WLST, system administrators and operators can initiate, manage, and persist WebLogic Server configuration changes.

See:

Web Services Custom WLST Commands in WLST Command Reference for Infrastructure Components
Understanding the WebLogic Scripting Tool

Using Oracle WebLogic Server Ant Tasks

WebLogic Server includes a variety of Ant tasks that you can use to centralize many of the configuration and administrative tasks into a single Ant build script. Use wlserver, wlconfig, and wldeploy for basic Ant tasks.

The Ant tasks can:

Create, start, and configure a new WebLogic Server domain, using the wlserver and wlconfig Ant tasks.
Deploy a compiled application to the newly-created domain, using the wldeploy Ant task.
Generate web services and clients, and download a WSDL to a local directory.

The following table summarizes the steps to use the web services Ant tasks.

Table 3-1 Steps to Use the Web Services Ant Tasks

#	Step	Description
1	Set up your environment.	On Windows NT, execute the `setDomainEnv.cmd` command, located in your domain directory. The default location of WebLogic Server domains is `ORACLE_HOME\user_projects\domains\domainName`, where `ORACLE_HOME` represents the directory you specified as the Oracle Home when you installed WebLogic Server and `domainName` is the name of your domain. On UNIX, execute the `setDomainEnv.sh` command, located in your domain directory. The default location of WebLogic Server domains is `ORACLE_HOME/user_projects/domains/domainName`, where `ORACLE_HOME` represents the directory you specified as the Oracle Home when you installed WebLogic Server and `domainName` is the name of your domain.
2	Create the `build.xml` file that contains a call to the web services Ant tasks.	The following example shows a simple `build.xml` file with a single target called `clean`: <project name="my-webservice"> <target name="clean"> <delete> <fileset dir="tmp" /> </delete> </target> </project> This `clean` target deletes all files in the `tmp` subdirectory. Later sections provide examples of specifying the Ant task in the `build.xml` file.
3	For each WebLogic web service Ant task you want to execute, add an appropriate task definition and target to the `build.xml` file using the `<taskdef>` and `<target>` elements.	The following example shows how to add the `jwsc` Ant task to the build file; the attributes of the task have been removed for clarity: <taskdef name="jwsc" classname="weblogic.wsee.tools.anttasks.JwscTask" /> <target name="build-service"> <jwsc attributes go here...> ... </jwsc> </target> Note: You can name the WebLogic web services Ant tasks anything you want by changing the value of the name attribute of the relevant `<taskdef>` element. For consistency, however, this document uses the names `jwsc`, `clientgen`, `wsdlc`, and `wsdlget` throughout.
4	Execute the Ant task or tasks specified in the `build.xml` file.	Type `ant` in the same directory as the `build.xml` file and specify the target. For example: prompt> ant build-service
5	Specify the context path and service URI used in the URL that invokes the web service. (Optional)	You can set this information in several ways, as described in Defining the Context Path of a WebLogic Web Service in Developing JAX-WS Web Services for Oracle WebLogic Server.

For more information, see:

Ant Task Reference in WebLogic Web Services Reference for Oracle WebLogic Server
The following sections in Developing Applications for Oracle WebLogic Server:
- Using Ant Tasks to Configure and Use a WebLogic Server Domain
- wldeploy Ant Task Reference

Setting the Classpath for the WebLogic Ant Tasks

Each WebLogic Ant task accepts a classpath attribute or element so that you can add new directories or JAR files to your current CLASSPATH environment variable.

The following example shows how to use the classpath attribute of the jwsc Ant task to add a new directory to the CLASSPATH variable:

<jwsc srcdir="MyJWSFile.java"
      classpath="${java.class.path};my_fab_directory"
   ...
</jwsc>

The following example shows how to add to the CLASSPATH by using the <classpath> element:

<jwsc ...>
   <classpath>
       <pathelement path="${java.class.path}" />
       <pathelement path="my_fab_directory" />
   </classpath>
...
</jwsc>

The following example shows how you can build your CLASSPATH variable outside of the WebLogic web service Ant task declarations, then specify the variable from within the task using the <classpath> element:

<path id="myClassID">
   <pathelement path="${java.class.path}"/>
   <pathelement path="${additional.path1}"/>
   <pathelement path="${additional.path2}"/>
</path>
<jwsc ....>
   <classpath refid="myClassID" />
...
</jwsc>

Note:

The Java Ant utility included in WebLogic Server uses the ant (UNIX) or ant.bat (Windows) configuration files in the WL_HOME\server\bin directory to set various Ant-specific variables, where WL_HOME is the top-level directory of your WebLogic Server installation If you need to update these Ant variables, make the relevant changes to the appropriate file for your operating system.

Differences in Operating System Case Sensitivity When Manipulating WSDL and XML Schema Files

Many WebLogic web service Ant tasks have attributes that you can use to specify a file, such as a WSDL or an XML Schema file.

The Ant tasks process these files in a case-sensitive way. This means that if, for example, the XML Schema file specifies two user-defined types whose names differ only in their capitalization (for example, MyReturnType and MYRETURNTYPE), the clientgen Ant task correctly generates two separate sets of Java source files for the Java representation of the user-defined data type: MyReturnType.java and MYRETURNTYPE.java.

However, compiling these source files into their respective class files might cause a problem if you are running the Ant task on Microsoft Windows, because Windows is a case insensitive operating system. This means that Windows considers the files MyReturnType.java and MYRETURNTYPE.java to have the same name. So when you compile the files on Windows, the second class file overwrites the first, and you end up with only one class file. The Ant tasks, however, expect that two classes were compiled, thus resulting in an error similar to the following:

c:\src\com\bea\order\MyReturnType.java:14: 
class MYRETURNTYPE is public, should be declared in a file named   MYRETURNTYPE.java 
public class MYRETURNTYPE 
       ^

To work around this problem rewrite the XML Schema so that this type of naming conflict does not occur, or if that is not possible, run the Ant task on a case sensitive operating system, such as Unix.

Using the Java Management Extensions (JMX)

A managed bean (MBean) is a Java bean that provides a Java Management Extensions (JMX) interface. JMX is the Java EE solution for monitoring and managing resources on a network. Like SNMP and other management standards, JMX is a public specification and many vendors of commonly used monitoring products support it.

WebLogic Server provides a set of MBeans that you can use to configure, monitor, and manage WebLogic Server resources through JMX. WebLogic web services also have their own set of MBeans that you can use to perform some web service administrative tasks.

There are two types of MBeans: runtime (for read-only monitoring information) and configuration (for configuring the web service after it has been deployed).

The configuration web services MBeans are:

WebserviceSecurityConfigurationMBean
WebserviceCredentialProviderMBean
WebserviceSecurityMBean
WebserviceSecurityTokenMBean
WebserviceTimestampMBean
WebserviceTokenHandlerMBean

The runtime web services MBeans are:

WseeRuntimeMBean
WseeHandlerRuntimeMBean
WseePortRuntimeMBean
WseeOperationRuntimeMBean
WseePolicyRuntimeMBean

See MBean Reference for Oracle WebLogic Server and the following sections in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server:

Using the Java EE Deployment API

The Java EE Deployment architecture defines the contracts that enable tools or application programmers to configure and deploy applications on any Java EE platform product. The contracts define a uniform model between tools and Java EE platform products for application deployment configuration and deployment.

In Java EE 5, the J2EE Application Deployment specification (JSR-88), described at http://jcp.org/en/jsr/detail?id=88, defines a standard API that you can use to configure an application for deployment to a target application server environment.

The Deployment architecture makes it easier to deploy applications: Deployers do not have to learn all the features of many different Java EE deployment tools in order to deploy an application on many different Java EE platform products.

See Deploying Applications to Oracle WebLogic Server for more information.

Using Web Services Apache Maven Goals

Apache Maven is a software tool for building and managing Java-based projects. WebLogic Server provides support for Maven through the provisioning of plug-ins that enable you to perform various operations on WebLogic Server from within a Maven environment.

WebLogic Server provides support for the following web services Maven goals.

Table 3-2 Web Services Maven Goals

Maven Goal	Description
`ws-clientgen`	Generates client web service artifacts from a WSDL.
`ws-wsdlc`	Generates a set of artifacts and a partial Java implementation of the web service from a WSDL.
`ws-jwsc`	Builds a JAX-WS web service.

See Using the WebLogic Development Maven Plug-in in Developing Applications for Oracle WebLogic Server for complete documentation.