Structure of a JWS File

A JWS file is a valid Java file. If you are not familiar with Java and would like to read about basic features of the language, see Introduction to Java.

This topic discusses the individual elements that occur in a JWS file. For a collection of examples of JWS files, see Sample Web Services.

# Parts of a JWS File

The following parts of a JWS file are described in this topic:

Package Statement

Import Statements

Class Declaration

Member Variables

Control Instances

JwsContext Object

Avoiding Improper Initialization

Callback Interface

Inner Classes

Methods

Internal Methods

# Package Statement

The package statement specifies the Java package in which the classes and objects in this file reside. In JWS files, 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 Project Tree Pane, WebLogic Workshop will update the package name in the moved file. However, you will still encounter situations in which you must correctly set the package name yourself.

# Import Statements

Before you can reference a class or object that is not defined in a Java file, 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 weblogic.jws.control.TimerControl;  // TimerControl API
    import weblogic.jws.control.JwsContext;    // service's execution context

# Class Declaration

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
    {
        ...
    }

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.

# Member Variables

The web service class may contain member variables.

    public class MyService
    {
        int myMemberVariable;
        ...
    }

Unannotated 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 Maintaining State with Conversations.

Some member variables are annotated as having special meaning. See the sections on Control Instances and the Callback Interface, below.

# Control Instances

If a member variable is annotated with the @jws:control tag, the member variable represents a control. Controls provide convenient interfaces to resources such as databases, Enterprise Java Beans (EJBs) or other web services.

    public class MyService
    {
        int myMemberVariable;

       /**
         *  @jws:control
         */
        TimerControl delayTimer;
        ...
    }

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

# JwsContext Object

Each JWS file may have a special member variable of type weblogic.jws.control.JwsContext annotated with the @jws:context tag. By default, new JWS files created by WebLogic Workshop contain such a member variable with the name context.

    public class MyService
    {

        int myMemberVariable;

       /**
         *  @jws:context
         */
        JwsContext context;
        ...
    }

If such a JwsContext instance is present in a JWS file, the instance may be used to access aspects of the JWS's context at runtime.

For more information on the JwsContext interface, see JwsContext Interface.

# Avoiding Improper Initialization

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 control instance is not populated. This code will throw a NullPointerException at runtime.

    public class MyService
    {
        /** @jws:control */
        private SomeServiceControl someService;
        ...
        String serviceResult = someService.getResult();
    }

The following code is correct:

    public class MyService
    {
        /** @jws:control */
        private SomeServiceControl someService;
        ...
        String serviceResult;

       /**
         * @jws:operation
         */
        public void someMethod()
        {
            ...
            serviceResult = someService.getResult();
            ...
        }
    }

# 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. When you add a callback to your service in the Design View, the signature for the callback method becomes a member of the callback interface.

    public class MyService
    {
        int myMemberVariable;

       /**
         *  @jws:control
         */
        TimerControl delayTimer;

        public static interface Callback
        {
            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 CTRL files, you may edit it manually if you wish.

The contents of the callback interface are exported to the WSDL file for your 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.

To learn how to document the callbacks your web service defines, see Documenting Web Services.

# Inner Classes

An inner class is a class declared within another class or interface. Common uses for inner classes include:

- arguments and return values of methods

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 Why Use XML Maps?

- mirror of a database record structure, into which query results can be mapped

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 it's result to an object of that class.

For more information on using a database from your service, see Database Control: Using a Database from Your Web Service.

The example below demonstrates declaration of Customer as an inner class of the MyService class.

    public class MyService
    {
        int myMemberVariable;

       /**
         *  @jws:control
         */
        TimerControl delayTimer;

       public static interface Callback
        {
            public void myCallback(String stringArg);
        }
        public Callback callback;

        public class Customer
        {
            public int custid;
            public String name;
            public String emailAddress;
        }
        ...
    }

# Methods

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 @jws:operation tag. 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
    {
        int myMemberVariable;

       /**
         *  @jws:control
         */
        TimerControl delayTimer;

       public static interface Callback
        {
            public void myCallback(String stringArg);
        }
        public Callback callback;

       public class Customer
        {
            public int custid;
            public String name;
            public String emailAddress;
        }

        /**
         *  @jws:operation
         */
        public String myMethod(String stringArg)
        {
            ...
        }

       ...
    }

To learn how to document the methods in your web service, see Documenting Web Services.

# Internal Methods

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
    {
        int myMemberVariable;

       /**
         *  @jws:control
         */
        TimerControl delayTimer;

       public static interface Callback
        {
            public void myCallback(String stringArg);
        }
        public Callback callback;

       public class Customer
        {
            public int custid;
            public String name;
            public String emailAddress;
        }

       /**
         *  @jws:operation
         */
        public String myMethod(String stringArg)
        {
            ...
        }

        private method myInternalMethod(int intArg)
        {
            ...
        }

       ...
    }

Related Topics

Introduction to Java

Sample Web Services