A JWS file contains a Java Web Service. This topic is an overview of the JWS file format.
A JWS file contains syntactically correct Java. However, a JWS file also has attributes that allow it to take advantage WebLogic Workshop's powerful facilities for web services:
A JWS file contains only the logic you need to implement your web service. All of the underlying infrastructure, protocols and web service lifecycle management are handled automatically by the WebLogic Workshop runtime.
The following parts of a JWS file are described in this topic:
The package statement specifies the Java package in which the classes and objects in this file reside. The package is dictated by the directory in the project within which the JWS file is located. If the JWS file is in the top level directory of the project, a package statement is not necessary. The file is in the default package for the project.
If the JWS file resides in a subdirectory of the project, the package name must reflect the directory hierarchy. For example, if the JWS file is in the <project>/financial/clientservices directory, it must contain the following package statement:
package financial.clientservices;
WebLogic Workshop attempts to manage the package statement for you. For example, if you move a JWS file from one directory to another using the Application pane, WebLogic Workshop will update the package name in the moved file. However, you may still encounter situations in which you must correctly set the package name yourself.
Before you can reference a class or object that is not defined directly in your Java class, you must import the definition of that class or object (or the package that defines it). You do so with import statements.
Packages or classes you might typically import in a JWS file include:
import com.bea.control.TimerControl; // TimerControl API import com.bea.control.JwsContext; // service's execution context
A JWS file must include the declaration of a single top-level public class. This is the class that defines your web service. The name of your web service is the name of this class. The class declaration for a web service called MyService would appear as follows:
public class MyService implements com.bea.jws.WebService
{
...
}
The implements com.bea.jws.WebService clause indicates that this class is a web service. The WebService Java interface is a marker interface only, it declares no methods.
All of the remaining items described in this topic are member variables or member functions of the web service's class.
To learn how to document your web service, see Documenting Web Services.
The web service class may contain member variables. These are variables whose scope is at the level of the class. Member variables declared in a JWS file are valid and are persisted as long as the instance of the class exists. If the web service is conversational, member variables are persisted per-conversation-instance for as long as each conversation exists.
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
...
}
Non-annotated member variables are normal members of the class. These member variables are automatically persisted and correlated with specific client conversations if the methods of the service are marked as conversational.
To learn more about conversations, see Designing Conversational Web Services.
Some member variables are annotated as having special meaning. See the sections on Control Instances and the Callback Interface, below.
If a member variable is annotated with the @jc:control annotation, the member variable represents a Java control. Java controls provide convenient interfaces to resources such as databases, Enterprise JavaBeans (EJBs), other web services or arbitrary business logic in custom Java controls.
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
/**
* @jc:control
*/
TimerControl delayTimer;
...
}
For more information on controls, see Working with Java Controls.
Each JWS file may have a special member variable of type com.bea.control.JwsContext annotated with the @common:context annotation.
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
/**
* @common:context
*/
com.bea.controlJwsContext context;
...
}
This instance of the JwsContext object may be used to access aspects of the web service's context at runtime.
For more information on the JwsContext interface, see JwsContext Interface.
Controls and context objects are not valid outside the scope of web service methods. Initialization code associated with the declarations of member variables of a JWS file is executed when the JWS class is instantiated. Since instantiation of the JWS class occurs outside of any particular web service method invocation, such initializations will fail or lead to unpredictable results if they reference controls or the context instance.
In the following example code, the serviceResult member variable is initialized by calling a method on the someService control. This code is not valid, since at the time the initialization code is executed the someService Web Service control instance is not populated. This code will throw a NullPointerException at runtime.
public class MyService implements com.bea.jws.WebService
{
/** @common:control */
private SomeServiceControl someService;
...
String serviceResult = someService.getResult();
}
The following code is correct:
public class MyService implements com.bea.jws.WebService
{
/** @common:control */
private SomeServiceControl someService;
...
String serviceResult;
/**
* @common:operation
*/
public void someMethod()
{
...
serviceResult = someService.getResult();
...
}
}
When you add a callback to your service in Design View, the signature for the callback method becomes a member of the Callback interface. The callback interface is an inner interface (an interface declared within another class or interface) of the JWS class, within which the callbacks to the client are defined. A Callback interface is automatically added to a web service's JWS file when a callback is added in Design View.
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
/**
* @common:control
*/
TimerControl delayTimer;
public static interface Callback extends com.bea.control.ServiceControl
{
public void myCallback(String stringArg);
}
public Callback callback;
...
}
The callback interface is managed for you by WebLogic Workshop. Although, as with all aspects of JWS and JCX files, you may edit it manually if you wish.
The callback interface is included in the WSDL file for your web service.
By specifying callbacks in your service, you are expressing an expectation that your service's clients will handle them. This may not be possible for some clients for a variety of reasons. Callbacks are a feature of asynchronous web services. To learn more about asynchronous web services, see Designing Asynchronous Interfaces.
An inner class is a class declared within another class or interface. Common uses for inner classes include:
If your web service publishes a method or callback that accepts or returns a Java object, the object will be translated to or from the class by an implicit or explicit XML map.
For more information on XML maps, see Introduction to XQuery Maps.
You can create an inner class with the member names and types that match the column names returned by a database query. You can then specify that a particular database query should map its result to an object of that class.
For more information on using a database from your service, see Database Control.
The example below demonstrates the declaration of Customer as an inner class of the MyService class.
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
/**
* @common:control
*/
TimerControl delayTimer;
public static interface Callback extends com.bea.control.ServiceControl
{
public void myCallback(String stringArg);
}
public Callback callback;
public class Customer
{
public int custid;
public String name;
public String emailAddress;
}
...
}
In this topic, methods are distinguished from internal methods, which are described in the next section.
The term method refers to a method that is exposed to clients of your service. A method is exposed to the client when it is marked with the @common:operation annotation. Methods that are exposed to the client must be declared with the public access modifier.
In the following example, myMethod is a method of the service MyService:
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
/**
* @common:control
*/
TimerControl delayTimer;
public static interface Callback extends com.bea.control.ServiceControl
{
public void myCallback(String stringArg);
}
public Callback callback;
public class Customer
{
public int custid;
public String name;
public String emailAddress;
}
/**
* @common:operation
*/
public String myMethod(String stringArg)
{
...
}
...
}
In this topic, internal methods are distinguished from methods, which are described in the preceding section.
The term internal method refers to a method that is not exposed to clients of your service. An internal method has no special annotation; it is a normal Java class member. Internal methods may be declared with whatever access modifier (public, private, protected) your design requires.
In the following example, myInternalMethod is an internal method of the service MyService:
public class MyService implements com.bea.jws.WebService
{
int myMemberVariable;
/**
* @common:control
*/
TimerControl delayTimer;
public static interface Callback extends com.bea.control.ServiceControl
{
public void myCallback(String stringArg);
}
public Callback callback;
public class Customer
{
public int custid;
public String name;
public String emailAddress;
}
/**
* @common:operation
*/
public String myMethod(String stringArg)
{
...
}
private method myInternalMethod(int intArg)
{
...
}
...
}