com.webobjects.eodistribution
Class EODistributionContext

java.lang.Object
  |
  +--com.webobjects.eodistribution.EODistributionContext

All Implemented Interfaces:

NSDisposable

public class EODistributionContext

extends Object

implements NSDisposable

EODistributionContext objects perform the server-side related work behind Java Client applications and take care of encoding and decoding enterprise objects and other data. While WOJavaClientComponent objects embed Java Client into WebObjects and configure the client-side parameters, distribution contexts take care of actually generating the responses to client- side requests. EODistributionContext objects track the state of the server side object graph and communicate changes to the client, thus keeping the client and server object graphs in sync.

The delegate of a distribution context plays an important role in Java Client since it can validate remote method invocations originating from client objects and can implement various security mechanisms. See the EODistributionContext.Delegate interface description for more details on security.

If no delegate is implemented and set, the default security mechanisms are as follows: All clients can access all class descriptions (entities) and they can access all objects of those class descriptions, but only the properties explicitly marked as client-side class properties. But be careful: If the client-side class properties are not set explicitly, they default to the server-side class properties. Thus if you just use an EOModel which is not explicitly prepared for Java Client, the client has access to the complete database.

But without a delegate implementation, clients are not allowed to remotely invoke any methods outside the enterprise objects they fetch -- except methods that begin with the prefix "clientSideRequest". Remote methods that have a name starting with "clientSideRequest" and are invoked on the distribution context itsself, on a remote method receiver registered with the distribution context or the invocation target's session (the most common case) bypass the delegate security mechanisms and are considered safe to be invoked by any client. The standard remote method invocations to run Java Client applications do not allow the delegate to intersect, but they offer more specialized delegate methods to control security.

To support arbitrary remote method invocations, for example to communicate directly with the session object to handle special authentication needs, clients can invoke remote methods on a target relative to the so-called invocationTarget of the distribution context, which by default is the WOJavaClientComponent. These remote methods can use a key path which is evaluated relative to the invocationTarget (the WOJavaClientComponent). By using a key path "session" for example, you reach the session of the WOJavaClientComponent.

But sometimes methods invoked by the client are not implemented on the session, but on other objects. To support an easy configuration of those methods, clients can also pass null as the key path of a remote method invocation target, in which case the distribution context goes through the list of objects registered with the addRemoteMethodReceiver method and invokes the method on the first registered receiver responding to the method to be invoked. Usually these remote method receivers are registered with the help of the RemoteMethodReceiverNeededNotification notification. Typically you register the WOApplication or another global object to receiver this notification from all distribution contexts and then, when received, add a list of remote method receivers to the distribution context.

See Also:

EODistributionContext.Delegate

Inner Class Summary

static interface

EODistributionContext.Delegate This interface defines the methods that can be implemented by the delegate of EODistributionContexts -- mostly to control security.

Field Summary

static String	DistributionContextInstantiatedNotification The name of the notification sent when a distribution context is instantiated.
static String	RemoteMethodReceiverNeededNotification The name of the notification sent when a distribution context needs the list of remote method receivers.

Constructor Summary

EODistributionContext(WOSession session)
Creates a new distribution context for the session session, using the session's defaultEditingContext as the editing context which controls the server side representation of the enterprise object graph fetched by the client.

EODistributionContext(WOSession session, EOEditingContext editingContext)
Creates a new distribution context for the session session, using editingContext as the editing context which controls the server-side representation of the enterprise object graph fetched by the client.

Method Summary

void	addRemoteMethodReceiver(Object target) Adds an object to the array of remote method receivers.
Object	delegate() Returns the delegate of the distribution context.
void	dispose() Prepares the receiver so it is disposed when Java performs garbage collection.
static NSArray	distributionContextsForSession(WOSession session) Returns a array of distribution contexts for a session.
EOEditingContext	editingContext() Returns the editing context used by the distribution context.
Object	invocationTarget() Returns the invocation target for remote method invocations which use a key path.
NSArray	remoteMethodReceivers() Returns the array of remote method receivers.
NSData	responseToClientMessage(NSData message) Invoked to generate a response to a remote method invocation of the client appliction.
WOSession	session() Returns the session for the distribution context.
void	setDelegate(Object delegate) Sets the delegate of the distribution context.
void	setInvocationTarget(Object invocationTarget) Sets the invocation target for remote method invocations which use a key path.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DistributionContextInstantiatedNotification

public static final String DistributionContextInstantiatedNotification

The name of the notification sent when a distribution context is instantiated. The new distribution context is the sender of the notification.

RemoteMethodReceiverNeededNotification

public static final String RemoteMethodReceiverNeededNotification

The name of the notification sent when a distribution context needs the list of remote method receivers. When receiving this notification, you can register receivers with addRemoteMethodReceiver. The new distribution context is the sender of the notification.

Constructor Detail

EODistributionContext

public EODistributionContext(WOSession session,
                             EOEditingContext editingContext)

Creates a new distribution context for the session session, using editingContext as the editing context which controls the server-side representation of the enterprise object graph fetched by the client.

Parameters:

session - the session to use with the distribution context

editingContext - the editing context to use with the distribution context

EODistributionContext

public EODistributionContext(WOSession session)

Creates a new distribution context for the session session, using the session's defaultEditingContext as the editing context which controls the server side representation of the enterprise object graph fetched by the client.

Parameters:

session - the session to use with the distribution context

Method Detail

addRemoteMethodReceiver

public void addRemoteMethodReceiver(Object target)

Adds an object to the array of remote method receivers. Remote method receivers are used as targets for remote method invocations which specify a null invocation target key path.

Parameters:

target - the remote method receiver

See Also:

RemoteMethodReceiverNeededNotification, remoteMethodReceivers()

delegate

public Object delegate()

Returns the delegate of the distribution context. The delegate can control security of remote method invocations.

Returns:

the delegate object

See Also:

EODistributionContext.Delegate, setDelegate(Object)

dispose

public void dispose()

Prepares the receiver so it is disposed when Java performs garbage collection.

Specified by:

dispose in interface NSDisposable

distributionContextsForSession

public static NSArray distributionContextsForSession(WOSession session)

Returns a array of distribution contexts for a session. Usually there is only one distribution context per session. However, if you use multiple WOJavaClientComponents in the same session (which is not recommended for the usual case and introduces several complications), there will be more than one.

Parameters:

session - the session to look the distribution contexts up for

Returns:

the array of distribution contexts for a session

editingContext

public EOEditingContext editingContext()

Returns the editing context used by the distribution context. This editing context controls the server-side representation of the enterprise object graph fetched by the client. Fetches and saves from the client side go through this editing context, so the enterprise objects in this editing context represent the server-side equivalent of the enterprise objects fetched to the client side.

Returns:

the editing context used by the distribution context

invocationTarget

public Object invocationTarget()

Returns the invocation target for remote method invocations which use a key path. If specified, the key path for those remote method invocations is evaluated relative to this invocation target.

Returns:

the invocation target

See Also:

setInvocationTarget(Object), remoteMethodReceivers()

remoteMethodReceivers

public NSArray remoteMethodReceivers()

Returns the array of remote method receivers.

Returns:

the array of remote method receivers

See Also:

RemoteMethodReceiverNeededNotification, addRemoteMethodReceiver(Object)

responseToClientMessage

public NSData responseToClientMessage(NSData message)

Invoked to generate a response to a remote method invocation of the client appliction. The data format of the client-server communication is in a private format and not documented.

Parameters:

message - the remote method invocation data in a private format

Returns:

the response to the invocation in a private format

session

public WOSession session()

Returns the session for the distribution context.

Returns:

the session object

setDelegate

public void setDelegate(Object delegate)

Sets the delegate of the distribution context. The delegate can control security of remote method invocations.

Parameters:

delegate - the delegate object

See Also:

EODistributionContext.Delegate, delegate()

setInvocationTarget

public void setInvocationTarget(Object invocationTarget)

Sets the invocation target for remote method invocations which use a key path. If specified, the key path for those remote method invocations is evaluated relative to this invocation target.

Parameters:

invocationTarget - the invocation target

See Also:

invocationTarget(), remoteMethodReceivers()