Building Web Services with WebLogic Workshop

Although XML, SOAP and WSDL form the core technologies behind a web service, a developer working with the WebLogic Workshop is for the most part freed from the cumbersome details of these technologies. WebLogic Workshop simplifies web service development by allowing the developer to focus on the application logic of the web service, rather than focusing on the complex syntax of XML, SOAP and WSDL files. With WebLogic Workshop you can take a functional approach to development tasks: you tell WebLogic Workshop how you want your web service to function, and WebLogic Workshop implements the core web service technologies according to your instructions. WebLogic Workshop's visual development environment provides a graphical representation of the web service under development, giving the developer a complete picture of the web service's different parts and how the web service connects to other software applications and data resources. The topic below explains the basic concepts required to begin building web services with WebLogic Workshop.

# JWS Files

The Java Web Service (JWS) file is the core of your web service. It contains the Java code that determines how your web service behaves. In fact, a JWS file is nothing other than an ordinary Java class file. In this respect, you can think of a web service built on WebLogic Workshop as a Java class which communicates with the outside world through XML messages. If you are unfamiliar with programming in Java, see Introduction to Java.

The WebLogic Workshop user interface offers two ways of viewing JWS files: Source View and Design View. Source View offers a direct view of the Java code within a JWS file; Design View offers a graphical representation of the code within a JWS file.

Just as you can view a web service in either Design View or Source View, you can also edit a web service in either Design View or Source View. As you make changes to a web service in Design View, WebLogic Workshop will make the corresponding changes to the underlying code; similarly, if you make changes to the code directly in Source View, those changes will automatically be reflected in Design View.

For more information on JWS files see JWS Files.

## Working with Design View

When you view a JWS file in Design View, the web service itself is depicted in the middle of the screen, the client application is depicted on the left side, and the web service's data resources are depicted on the right side. The client, the application which calls your web service, might be a Java application, a VisualBasic application, or another web service—any application designed to send and receive XML messages. Similarly, the data resources for your web service can be any sort of application, such as a database or another web service, provided it can send and receives XML messages. As a general rule, when you are building a new web service, you should begin in Design View. In the initial Design View stage you can define what data resources your web service will draw from, and how your web service interacts with its client application and its data resources. Once you have defined the basic shape of your web service in Design View, then begin working in Source View, where you can define the details of the interior implementation of your web service.

For more information about Design View, see User Interface Reference.

# Client Interface

If you examine any web service (that is, any JWS file) in Design View you will see arrows bridging the gap between the client application and the web service. These arrows represent the interface, or "public contract", between the client and the web service. Arrows pointing from the client toward the web service represent the methods through which the client application invokes the functionality of the web service. (Note that methods which are exposed to the client are sometimes referred to as operations to distinguish them from other methods in your web service.) Arrow pointing from the web service toward the client represent callbacks. Callbacks are one of the ways that your web service can send information back to the client application. Callbacks are especially useful for communication in network contexts, because callbacks make it possible for a client application to continue with its own processes instead of halting and waiting for a response from a slow or otherwise delayed web service. For example, if the web service is called upon to perform a time consuming operation, it can free up the client's own processes by immediately sending an acknowledgement of the client's request instead of the full result of the operation. Once the operation is complete the web service can send the full result via a callback to the client. This style of inter-application communication is called asynchronous communication, as opposed to synchronous communication, which requires that a client synchronize its own processes with the processes it invokes on another machine. Hence in synchronous communication, the client application may have to halt and wait for the full results to be returned whenever an operation it invokes an operation on an external machine.

For a more detailed treatment of asynchronous communications in web services see Using Asynchrony to Enable Long-Running Operations.

# Controls

When you build a web service that must draw data from other resources—such as databases, legacy applications, and other web services—you can incorporate those resources into your design by using controls. Controls manage the communication between a web service and a data resource by means of control methods and callback handlers. Control methods (depicted as arrows pointing from the web service, through the control, to the data resource) allow the web service to invoke the functionality of the data resource; callback handlers (depicted as arrows pointing from the data resource, through the control, to the web service) allow the web service to listen for and receive callbacks from the data resource.

Note that the underlying Java code for a control is not incorporated directly into a web service's JWS file, instead the code for a control appears in a separate CTRL file. This kind of file allows you to reuse the same control in many different web services without repeatedly writing the same Java code.

Controls greatly simplify the complex task of making your web service inter-operate with other applications. Instead of building piecemeal, ad hoc interfaces between your web service and other applications, controls provide a single model for interfacing with a wide variety of different applications. Whether the application is a database or another web service, controls let your web service access the application simply by calling control methods directly from the Java code of your web service. Moreover, WebLogic Workshop provides powerful tools for autogenerating controls. For example, WebLogic Workshop will automatically generate a CTRL file based on a WSDL file, allowing your web service easy interface with any other web service on the internet.

WebLogic Workshop supports the following kinds of controls:

Service control — A Service control provides an interface to another web service, allowing your service to invoke the methods and handle the callbacks of the other service. The other web service can be one developed with WebLogic Workshop or any web service for which a WSDL file is available.

Timer control — A Timer control notifies your web service when a specified period of time has elapsed or when a specified absolute time has been reached.

EJB control — An EJB control provides an interface for access to Enterprise Java Beans (EJBs). EJBs are Java software components of enterprise applications.

Database control — A Database control provides access to a relational database, allowing a web service to query the database by calling Java methods and operating on Java objects . The Database control automatically performs the translation from database queries to Java objects and vice versa.

JMS control — A JMS control enables web services to easily interact with messaging systems that provide a Java Message Service (JMS) implementation.

For more information about controls, see Controls: Using Resources from a Web Service.

# Setting Properties

Another way that WebLogic Workshop lets you focus on application logic rather than the complexities of the underlying web service technologies is through setting properties of your web service directly through the graphical user interface. Instead of writing complex Java code to make you web service support enterprise level features, you can simply use WebLogic Workshop to make your web service implement these features. Each item in your service design, from individual methods, up through controls, and including the whole web service itself, exposes its own set of properties which can be modified directly through Design View.

Examples of functionality you can use merely by setting properties include:

- Message buffering, a technology that places incoming and outgoing XML messages into a queue for better handling of high demand.

- Conversations, a technology through which WebLogic Server maintains your service's state and correlates its communications. For more information about conversations see Maintaining State with Conversations.

- Protocols (HTTP, JMS, etc.) that may be used to access your service.

Setting properties in Design View adds Javadoc annotations to your source code. Originally a technology for extracting in-source documentation (hence the name), Javadoc technology is ideal for associating properties with aspects of your web service.

Javadoc tags used in WebLogic Workshop begin with an @jws prefix. The @ symbol is a Javadoc convention that signals to the compiler the presence of a word that should be interpreted as a Javadoc tag. The "jws" prefix stands for "Java Web Service" and differentiates web service tags from other Javadoc tags (for instance, you may use your own Javadoc tags to embed documentation about your web services).

The following example contains three Javadoc tags: @jws:operation specifies that the requestReport method should be exposed to be called by clients; @jws:conversation specifies that the requestReport method starts a conversation; and @jws:message-buffer specifies that the XML messages to and from the requestReport method should be queued.

/**
* @jws:operation
* @jws:conversation phase="start"
* @jws:message-buffer enable="true"
*/
public void requestReport(String id)
{...}

For reference information on Javadoc tags, see Javadoc Tag Reference.

# XML Maps

Because a web service communicates with external applications via XML messages, much of the work of building a web service involves translating back and forth between XML and whatever language implements the interior application logic of your web service. If your web service's interior implementation is written in Java, then outgoing messages need to be translated from Java method calls into the appropriate XML message; likewise incoming XML messages need to be translated into the appropriate Java method calls. In the case of WebLogic Workshop all of this translation work is done for you—you don't need to write any scripts to parse apart incoming XML messages or put together outgoing XML messages. However, if necessary, WebLogic Workshop does allow you to access and customize the process of XML-Java translation via the use of XMLMaps and ECMAScript.

For more information about XML maps see Handling and Shaping XML Messages with XML Maps.