Additional Functions

This chapter describes additional functions that are used to implement EJB in JEUS.

1. WorkArea Service

The Work Area service enables a program to continuously propagate a particular implicit context. Like with a security context or transaction context, even if the implicit context is not propagated as a separate argument, it will automatically be transmitted during a local or remote method invocation. Work Area can be used when it is needed to transmit a context or there are multiple method arguments.

As a kind of user repository, Work Area is stored as a map in the form of a name-value pair. When Work Area is newly started, it gets transmitted with the current thread, and so it can continuously be used inside the same component as that of the invoked method or EJB. It also gets propagated during a remote EJB invocation.

The UserWorkArea interface, jeus.workarea.UserWorkArea, is used to access the Work Area service.

  1. For detailed information about the API, refer to the jeus.workarea package in JEUS API JavaDoc.

  2. Currently, the remote Work Area propagation function is available both in EJB 2.0 and 3.0 version. It is also available when using IIOP invocation instead of JEUS basic RMI invocation.

1.1. UserWorkArea Interface

The UserWorkArea interface defines all methods required to start, close, and operate UserWorkArea as follows.

<UserWorkArea Interface>
public interface UserWorkArea {
   public void begin(String name);
   public void complete()
          throws NoWorkAreaException, NotOriginatorException;
   public String getName();
   public String[] retrieveAllKeys();
   public void set(String key, java.io.Serializable value)
          throws NoWorkAreaException, NotOriginatorException,
                 PropertyReadOnlyException;
   public void set(String key, java.io.Serializable value, PropertyModeType mode)
          throws NoWorkAreaException, NotOriginatorException,
                 PropertyReadOnlyException;
   public java.io.Serializable get(String key);
   public PropertyModeType getMode(String key);
   public void remove(String key)
          throws NoWorkAreaException, NotOriginatorException,
                 PropertyReadOnlyException;
}

For more information about method definition, refer to JavaDoc.

1.2. PropertyModeType

Each value stored in the WorkArea has its own PropertyMode setting.

Each PropertyMode Type is as follows:

Type Description

NORMAL

Enables used to modify and delete values registered in UserWorkArea.

READ_ONLY

Disables user to modify and delete values registered in UserWorkArea.

1.3. Exceptions

Exceptions defined for UserWorkArea are as follows:

Exception Description

WorkAreaException

The top-level exception that can occur in WorkArea.

NotOriginatorException

Occurs when trying to modify or delete a value or close a Work Area from a thread that did not initiate the work area.

PropertyReadOnlyException

Occurs when trying to modify a value whose PropertyMode is set to READ_ONLY.

1.4. Nested UserWorkArea

UserWorkArea can be nested. If a new UserWorkArea is started while one already exists, the new one is nested inside the existing UserWorkArea.

The nested UserWorkArea can use values from the parent UserWorkArea, and can also add new values. The values added by the nested UserWorkArea are available only in the nested UserWorkArea, and they will be removed when the nested UserWorkArea is terminated.

Registration information in the nested UserWorkAreas is as follows:

figure user workarea nested
Registration Information in Nested UserWorkArea

1.5. Developing Application Programs that Use UserWorkArea

This section shows an example of EJBs using the UserWorkArea interface.

The example consists of two EJBs, the UserWorkAreaSampleSender and UserWorkAreaSampleReceiver. In the example, the sender creates the UserWorkArea and transmits data, and the receiver creates a message using the specified value in UserWorkArea and returns the message to the original sender.

  1. UserWorkArea Access

    To use the UserWorkArea, JNDI has to look up the UserWorkArea.

    The following example shows how JNDI looks up the UserWorkArea.

    Access to UserWorkArea: <UserWorkAreaSampleSenderBean.java>
    public class UserWorkAreaSampleSenderBean implements UserWorkAreaSampleSender {
    public String getMessage() {
        InitialContext ic;
        String message = null;
        try {
           ic = new InitialContext();
           //Retrieve UserWorkArea from JNDI.
           UserWorkArea userWorkArea
             = (UserWorkArea) ic.lookup("java:comp/UserWorkArea");
        } catch (NamingException e) {
            // Do Something...
        }
        return message;
    }
}

  2. Starting a New UserWorkArea

    A new UserWorkArea needs to be started, because there was no information available for the first UserWorkArea that was looked up in JNDI. If a UserWorkArea name returned is null, NullPointerException occurs.

    Starting New UserWorkArea: <UserWorkAreaSampleSenderBean.java>
    public class UserWorkAreaSampleSenderBean implements UserWorkAreaSampleSender {
    public String getMessage() {
        InitialContext ic;
        String message = null;
        try {
          ic = new InitialContext();
          UserWorkArea userWorkArea
            = (UserWorkArea) ic.lookup("java:comp/UserWorkArea");
          // Starts a new UserWorkArea.
          userWorkArea.begin("UserWorkArea1");
        } catch (NamingException e) {
            // Do Something...
        }
        return message;
    }
}

  3. Configuring Registration in WorkArea

    Configuring registration information in the new UserWorkArea. The registration information includes <key, value, mode>. The key is String, and the value is a serializable object.

    If there is no UserWorkArea when configuring the value, a NoWorkAreaException occurs. If the UserWorkArea has not started yet, a NotOriginatorException occurs, and if a value which is already set to READ_ONLY is tried to be modified, a PropertyReadOnlyException occurs.

    Configuring Registration in WorkArea: <UserWorkAreaSampleSenderBean.java>
    public class UserWorkAreaSampleSenderBean implements UserWorkAreaSampleSender {
    public String getMessage() {
        InitialContext ic;
        String message = null;
        try {
            ic = new InitialContext();
            UserWorkArea userWorkArea
              = (UserWorkArea) ic.lookup("java:comp/UserWorkArea");
            userWorkArea.begin("UserWorkArea1");
            // Set userWorkArea as NORMAL.
            userWorkArea.set("name", "johan");
            // Set userWorkArea as READ_ONLY.
            userWorkArea.set("company", "TmaxSoft", PropertyModeType.READ_ONLY);
            UserWorkAreaSampleReceiver receiver
              = (UserWorkAreaSampleReceiver) ic.lookup("receiver");
            message = receiver.createMessage();
        } catch (NamingException e) {
            // Do Something...
        } catch (NoWorkAreaException e) {
            // Do Something...
        } catch (PropertyReadOnlyException e) {
            // Do Something...
        } catch (NotOriginatorException e) {
            // Do Something...
        }

        return message;
    }
}

  4. Obtaining Registration Information Configured in WorkArea

    Creates a message by using the registration information configured in UserWorkArea that was propagated from the receiver. Null is returned if a key, which does not exist in the UserWorkArea, is used when getting the information.

    Obtaining Registration Information Configured in WorkArea: <UserWorkAreaSampleReceiverBean.java>
    public class UserWorkAreaSampleReceiverBean implements UserWorkAreaSampleReceiver {
    public String createMessage() {
        InitialContext ic;
        String message = null;
        try {
            ic = new InitialContext();
            UserWorkArea userWorkArea
              = (UserWorkArea) ic.lookup("java:comp/UserWorkArea");
            // Retrieve settings from UserWorkArea.
            String name = (String)userWorkArea.get("name");
            String company = (String)userWorkArea.get("company");
            message = "Hello " + name + " from " + company;

        } catch (NamingException e) {
            // Do Something...
        }

        return message;
    }
}

  5. Completing UserWorkArea

    Completes the UserWorkArea that was started. Only the originator who started the UserWorkArea can complete it, and if others attempt to complete it, a NotOriginatorException occurs.

    Completing UserWorkArea: <UserWorkAreaSampleSenderBean.java>
    public class UserWorkAreaSampleSenderBean implements UserWorkAreaSampleSender {
    public String getMessage() {
        InitialContext ic;
        String message = null;
        try {
            ic = new InitialContext();
            UserWorkArea userWorkArea
              = (UserWorkArea) ic.lookup("java:comp/UserWorkArea");
            userWorkArea.begin("UserWorkArea1");
            userWorkArea.set("name", "user1");
            userWorkArea.set("company", "TmaxSoft", PropertyModeType.READ_ONLY);
            UserWorkAreaSampleReceiver receiver
              = (UserWorkAreaSampleReceiver) ic.lookup("receiver");
            message = receiver.createMessage();
            userWorkArea.complete(); // Shut down UserWorkArea.

        } catch (NamingException e) {
            // Do Something...
        } catch (NoWorkAreaException e) {
            // Do Something...
        } catch (PropertyReadOnlyException e) {
            // Do Something...
        } catch (NotOriginatorException e) {
            // Do Something...
        }

        return message;
    }
}