Hosted Entities
http://plover.sourceforge.net \| Last published: 03 April, 2005

Executive Summary

Home

Overview

License

Download

Project Summary

Change Notes

Using Plover

Installation

Configuration

Hosted Entities

Client-side Invocation

Network Discovery

API Documentation

This project is hosted on

About Hosted Entities

Hosted entities are items that exist on the server-side Plover environment and encapsulate functionality as high-level method calls. These methods, if public, are subject to invocation from a remote invocation environment on the client-side of the application.

Hosted entities are implemented either as Java classes or Javascript code fragments. The Javascript implementations are interpreted at runtime using BeanShell lightweight scripting. Javascripted entites are therefore more dynamic as far as changes go, but take more time to execute and are not recommended for complex entity logic. You might want to use Javascript when in development mode, or when the entities serve as trivial adapters to business logic implemented elsewhere (e.g. EJB).

An Example Hosted Entity

In this section we will create an example hosted entity: the user manager. This entity will be used to perform user administration in the form of create, modify, list and delete user accounts on the server. Let us start by creating the skeleton of such a class using plain Java.




import omd.plover.hosting.spi.*;



public class UserManagerEntity extends DefaultServerObject

{

    public void addUser(UserData data) throws UserException

    {   // Add user implementation

    }



    public void updateUser(UserData data) throws UserException

    {   // Update user implementation.

    }



    public Vector listUsers()

    {   // List user implementation.

    }



    public void deleteUser(String userName) throws UserException

    {   // Delete user implementation.

    }

}

The UserData class is a JavaBean style data object that contains information about one user account. The UserException class signals a error condition during user management operations.

Your custom hosted entity must either derive from the DefaultServerObject class or implement the IEntityObject interface. The entity class must only have the default (no-arg) constructor. During instantiation, the entity is provided with an instance of IEntityContext that defines a set of methods that the entity can use to communicate with the hosting environment. Deriving from DefaultServerObject has the benefit of having the entity context available as a protected attribute called context with associated setter method.

To represent the same functionality in a Javascript, create a file called UserManagerEntity.script. Then copy the same directives and method definitions as above with the exception of the class declaration.




public void addUser(UserData data) throws UserException

{   // Add user implementation

}



public void updateUser(UserData data) throws UserException

{   // Update user implementation.

}



public Vector listUsers()

{   // List user implementation.

}



public void deleteUser(String userName) throws UserException

{   // Delete user implementation.

}

When using a Javascript to implement hosted entities, the IEntityContext instance is available as the implicit variable context to all instructions within the script.

Exporting the Hosted Entity

Exporting the user manager entity amounts to creating an entry in the configuration XML for the Plover server-side environment. This is as illustrated below:

<object-entity id="userMgr" type="UserManagerEntity" />

<script-entity id="userMgr" path="UserManagerEntity.script" />

Exporting an entity implies that the entity is now ready for remote invocation from a client environment. This operation also ensures uniform referencing scheme for entities with different implementation mechanisms.

Life Cycle of Hosted Entities

For normal export scenarios, like the one above, the export operation maintains a link between the entity identifier and the name of the implementing Java class or script file. The actual entity gets instantiated only at the time of method invocation against the entity identifier. Instantiations are atomic at the method level. For two sequential method calls on the same entity, two entity instances get created and destroyed.

A hosted entity can be exported with the sticky flag set. This makes the entity stateful across mutiple method calls from the same client.

<object-entity id="userMgr" type="UserManagerEntity" sticky="true" />

<script-entity id="userMgr" path="UserManagerEntity.script" sticky="true" />

This implies that one instance of the user manager entity gets created for each client session, the first time it is referenced in a remote call. The same instance is reused for subsequent method calls in the same session. The entity instance gets destroyed only when the client session terminates.

Method Arguments, Return Types and Exceptions

All arguments passed to remotely accessible methods must either be a primitive data type or be serializable following the Java specifications for object serialization. The same holds true for return types and exception classes thrown.

File Location for Javascript Entities

The file location for Javascript entities can be specified either as absolute or relative paths on the local machine. For a Plover host that is launched from within a servlet container, a relative path for script files assumes the root to be the folder WEB-INF/scripts within the web application. For a Plover host that is lauched as part of a generic service, a relative path for script files assumes the root to be the current working directory of the containing application.

For non-Web platforms, you can specify a root folder for relative script file paths that is different from the current application directory. This is possible only using API-based configuration using the method call setScriptBase() on the IHostConfig interface.