# Stateful Webservice

## Introduction

&jax-ws.product.name.short; has a vendor extension that allows developers to bring back object state to the web service world. Normally, &jax-ws.product.name.short; only creates one instance of a service class, and have it serve all incoming requests concurrently. This makes it essentially impossible to use instance fields of the service class for any meaningful purpose.

Because of this, people end up coding like C, in anti-OO fashion. Either that or you end up with writing boiler-plate code to dispatch a request to the right instance of your real domain object.

The stateful web service support in &jax-ws.product.name.short; resolves this problem by having &jax-ws.product.name.short; maintain multiple instances of a service. By using users-guide-ws-addressing behind the scene, it provides a standard-based on-the-wire protocol and easy-to-use programming model.

## Usage

Application service implementation classes (or providers) who'd like to use the stateful web service support must declare `@Stateful` annotation on a class. It should also have a public static method/field that takes `StatefulWebServiceManager`.

    @Stateful
    @WebService
    @Addressing
    class BankAccount {

        protected final int id;
        private int balance;

        BankAccount(int id) {
            this.id = id;
        }

        @WebMethod
        public synchronized void deposit(int amount) {
            balance += amount;
        }

        // either via a public static field

        public static StatefulWebServiceManager<BankAccount> manager;

        // ... or  via a public static method (the method name could be
        // anything)

        public static void setManager(StatefulWebServiceManager<BankAccount>
                                              manager) {
            // ...
        }

    }

After your service is deployed but before you receive a first request, the resource injection occurs on the field or the method.

A stateful web service class does not need to have a default constructor. In fact, most of the time you want to define a constructor that takes some arguments, so that each instance carries certain state (as illustrated in the above example).

Each instance of a stateful web service class is identified by an unique `EndpointReference`. Your application creates an instance of a class, then you'll have &jax-ws.product.name.short; assign this unique EPR for the instance as follows:

    @WebService
    class Bank { // this is ordinary stateless service

        @WebMethod
        public synchronized W3CEndpointReference login(int accountId,
                                                       int pin) {
            if (!checkPin(pin))
                throw new AuthenticationFailedException("invalid pin");
            BankAccount acc = new BankAccount(accountId);
            return BankAccount.manager.export(acc);
        }

    }

Typically you then pass this EPR to remote systems. When they send messages to this EPR, &jax-ws.product.name.short; makes sure that the particular exported instance associated with that EPR will receive a service invocation.

## Things To Consider

When you no longer need to tie an instance to the EPR, use `unexport(Object)` so that the object can be GC-ed (or else you'll leak memory). You may choose to do so explicitly, or you can rely on the time out by using `setTimeout(long, Callback)`.

`StatefulWebServiceManager` is thread-safe. It can be safely invoked from multiple threads concurrently.