com.webcab.ejb.math.optimization
Interface FunctionDelivery

All Superinterfaces:

Serializable

All Known Implementing Classes:

LocalFunctionDelivery, RMIFunctionDelivery

public interface FunctionDelivery

extends Serializable

All FunctionDelivery parameters in the remote and home interfaces use a special mechanism for sending instances of user-defined types over to the EJB components. A user-defined type is a class written by the developer on his/her client machine.

EJB methods that take user-defined types for parameters also expect your user-defined type class to implement a certain interface part of the product. The following example describes how to use the Function Delivery mechanism.

A Typical Example

Reading the EJB Method JavaDocs

Assume for example that an EJB component has a method named analyzeFunction with one FunctionDelivery parameter. Assume that the API documentation (the JavaDocs) for this method specifies that the user-defined type must implement interface OneDimensionalFunction, within the same package. You can also tell the name of the interface from the name of the parameter, which in this case would be deliveryOfOneDimensionalFunction.

Writing the User-Defined Type

Your user-defined type must be a class which implements OneDimensionalFunction. Implementing an interface comes down to writing the code for each of its methods. If we assume OneDimensionalFunction defines the following method (corresponding to the function f(x) = x):

     double getFunctionValue (double pointOfEvaluation)
 

then the user-defined type must define the code for the getFunctionValue method. We'll assume your user-defined type class is called MyFunction and looks like this:

     public class MyFunction implements OneDimensionalFunction {
         // The implementation for the interface method
         public double getFunctionValue (double pointOfEvaluation) {
             return pointOfEvaluation;
         }
     }
 

If we had wished to provide the function which evaluates the trigonometric sine of an angle pointOfEvaluation, then we would define the class as follows:

     public class MyFunction implements OneDimensionalFunction {
         // The implementation for the interface method
         public double getFunctionValue (double pointOfEvaluation) {
             return Math.sin(pointOfEvaluation);
         }
     }
 

Similarly, if we had wished to implement the polynomial f(pointOfEvaluation) = 2(pointOfEvaluation)2 + 3, then we would define the following class:

     public class MyFunction implements OneDimensionalFunction {
         // The implementation for the interface method
         public double getFunctionValue (double pointOfEvaluation) {
             return 2 * (pointOfEvaluation * pointOfEvaluation) + 3;
         }
     }
 

Creating a User-Defined Type Instance

What you actually send to the EJB method is an instance of your user-defined type, not the class itself. That is, you create an instance by invoking any of the constructors you have defined within your user-defined type. If you have not defined any constructors at all -- like in our code above -- you can call the no-arguments constructors as follows:

     MyFunction myFunctionInstance = new MyFunction ();
 

Creating a Function Delivery Instance

Recall from above that the EJB method we wish to call is named analyzeFunction. This method takes an instance of a FunctionDelivery class, not an instance of your user-defined type. There are two classes you can choose from, one for each of the delivery mechanism we have implemented:

1. Local Function Delivery (recommended)
2. RMI Function Delivery (advanced)

The local delivery mechanism copies your user-defined type instance to the EJB server so that direct calls can be made to it. The RMI delivery mechanism leaves the instance on the client-side machine, while all calls to the instance are made over the network, from server to client. User-defined types which use client-side resources (such as other user-defined types) will need to use the RMI delivery mechanism. Otherwise, if the user-defined type is self-sufficient (makes calls only to the standard Java packages and uses no client-side resources), the local delivery mechanism is the best choice. For more details, please follow the corresponding links above and/or check the client examples we provided in this package.

In most cases, you will only use the local delivery mechanism, as it is faster and doesn't require any extra code to write (as opposed to the RMI mechanism). What you will send to the EJB method is an instance of the LocalFunctionDelivery class, which you will create as follows:

     FunctionDelivery delivery = new LocalFunctionDelivery (myFunctionInstance);
 

Sending the User-Defined Type Instance

All that is left now is to send in to the EJB method the FunctionDelivery instance we have just created above. The code for invoking the analyzeFunction EJB method is:

     ejbComponent.analyzeFunction (delivery);
 

where ejbComponent is the EJB instance of the EJB component you are using. To summarize, here is the code we would write to invoke the EJB Method using the Function Delivery mechanism:

     MyFunction myFunctionInstance = new MyFunction ();
     FunctionDelivery delivery = new LocalFunctionDelivery (myFunctionInstance);
     ejbComponent.analyzeFunction (delivery);
 

Writing it as a One-Liner

In many cases you would avoid writing the last three steps separately (Creating a User-Defined Type Instance, Creating a Function Delivery Instance, and Sending the User-Defined Type Instance). Instead, you can create the two instances while invoking the EJB method. In our case, you would merge the three lines of code as follows:

     ejbComponent.analyzeFunction (new LocalFunctionDelivery (new MyFunction ()));
 

For further details about how to use the Local Delivery and other ways of delivering your user-defined types, please follow the links in the See Also section below and run the client examples we have provided within this package.

See Also:

RMIFunctionDelivery, LocalFunctionDelivery

Method Summary

Serializable

getDelivery()

Method Detail

getDelivery

public Serializable getDelivery()
                         throws Exception

Exception