arlut.csd.ganymede
Class ReturnVal

java.lang.Object
  |
  +--arlut.csd.ganymede.ReturnVal

All Implemented Interfaces:

java.io.Serializable

public class ReturnVal

extends java.lang.Object

implements java.io.Serializable

This class provides a report on the status of the client's requested operation. It is intended to be returned by a call on the server to make a change to the database.

Included in this object is a general success code, a list of objects and fields that need to be rescanned, if applicable, a dialog resource that can provide a description of a dialog box to be presented to the user, and an optional callback that the client can call with the results of the dialog box if necessary.

Note that operations that succeed without needing any further information or action on the part of the client will simply return null.

If a non-null ReturnVal object is passed back, one of two things may be true. didSucceed() may return true, in which case the operation was successful, but there may be an informational dialog returned and/or a list of objects and fields that need to be updated in response to the successful update.

Alternatively, didSucceed() may return false, in which case the operation either could not succeed or is incomplete. In this case, doRescan() will return false, and getDialog() should return a valid JDialogBuff. If the operation is simply incomplete pending more data from the user, getCallback() will return a non-null value. In this case, the user should be presented the dialog box, and the results of that dialog should be passed to the callback. The callback will in return pass back another ReturnVal object. The server may walk the user through an iterative set of dialogs to finally complete the desired operation.

See Also:

JDialogBuff, DialogRsrc, StringDialog, Ganymediator, Serialized Form

Field Summary

private arlut.csd.ganymede.Ganymediator	callback A Remote handle to a Wizard object on the server
(package private) static boolean	debug
static byte	DELETED
private arlut.csd.JDialog.JDialogBuff	dialog A Serializable Dialog Definition
boolean	doNormalProcessing This boolean variable is used on the server side only, to determine whether the field code that invoked wizardHook on a DBEditObject subclass should continue with its normal process or whether it should immediately return this ReturnVal to the (client-side) caller.
static byte	EXPIRATIONSET
static byte	LAST
(package private) arlut.csd.ganymede.Invid	newObjectInvid A Serializable Invid that can be returned in response to certain operations on the server.
static byte	NONE
(package private) arlut.csd.ganymede.db_object	remoteObjectRef A remote handle to a db_object on the server returned for use by the client.
private java.util.Hashtable	rescanHash Maps Invid's to RescanBuf's.
private java.lang.StringBuffer	rescanList A Serializable StringBuffer representation of objects and fields that need to be rescanned.
(package private) static long	serialVersionUID
(package private) byte	status
(package private) boolean	success

Constructor Summary

ReturnVal(boolean success)

ReturnVal(boolean success, boolean doNormalProcessing)

Method Summary

void	addRescanField(arlut.csd.ganymede.Invid objID, short fieldID) This method makes a note in this ReturnVal to have the client rescan field fieldID in object objID.
private void	breakOutRescanList() This private method converts the rescanList StringBuffer to a Hashtable (rescanHash) that maps Invid's to either Vector of Short's or "all".
void	clear()
private java.util.Hashtable	decodeRescanList(java.lang.StringBuffer buffer, java.util.Hashtable original) This method takes a StringBuffer encoded as follows:
boolean	didSucceed() This method returns the general success code for the preceding operation.
boolean	doRescan() This method returns true if this ReturnVal encodes rescan information for one or more fields in on or more objects.
java.lang.String	dumpRescanInfo() This method returns an encoded string representing the objects and fields to be rescanned by the client in response to this ReturnVal.
private void	encodeRescanList(java.util.Hashtable rescanTable) This method takes a Hashtable mapping Invid's to Vectors of Short field identifiers or the String "all" and generates the StringBuffer to be serialized down to the client.
arlut.csd.ganymede.Ganymediator	getCallback() If the server is asking for more interaction from the user to complete this operation, this method will return an RMI handle to a callback on the server.
arlut.csd.JDialog.JDialogBuff	getDialog() If the operation was not successful, this method should return a dialog box describing the problem and, potentially, asking for more information to complete the operation.
java.lang.String	getDialogText() If the operation was not successful, this method should return a the text of any encoded dialog box describing the problem.
arlut.csd.ganymede.Invid	getInvid() This method is used to get an Invid that the server wants to return to the client.
arlut.csd.ganymede.db_object	getObject() This method is used to get a remote db_object reference that the server wants to return to the client.
byte	getObjectStatus() Certain operations may set status codes.
java.util.Vector	getRescanList(arlut.csd.ganymede.Invid objID) This method returns a Vector of Short() objects if the server provided an explicit list of fields that need to be reprocessed, or null if all or no fields need to be processed.
java.util.Vector	getRescanObjectsList() This method returns a Vector of Invid objects, corresponding to those objects which need to have some field rescan work done.
boolean	rescanAll(arlut.csd.ganymede.Invid objID) This method returns true if the server is requesting that all fields in the object referenced by the client's preceding call to the server be reprocessed.
void	setCallback(arlut.csd.ganymede.Ganymediator callback) This method attaches a remote reference to a Ganymediator wizard-handler to this ReturnVal for extraction by the client.
void	setDialog(arlut.csd.JDialog.JDialogBuff dialog) This method attaches a dialog definition to this ReturnVal for extraction by the client.
void	setInvid(arlut.csd.ganymede.Invid invid) This method is used to set an Invid that the client can retrieve from us in those cases where a method on the server really does need to return an Invid _and_ a return val.
void	setObject(arlut.csd.ganymede.db_object object) This method is used to set a db_object reference that the client can retrieve from us in those cases where a method on the server really does need to return a db_object _and_ a return val.
void	setRescanAll(arlut.csd.ganymede.Invid objID) This method makes a note in this ReturnVal to have the client rescan all fields in object objID.
void	setStatus(byte status)
arlut.csd.ganymede.ReturnVal	unionRescan(arlut.csd.ganymede.ReturnVal retVal) unionRescan merges field and object rescan requests from the supplied ReturnVal with and rescan requests we contain.

Methods inherited from class java.lang.Object

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

Field Detail

debug

static final boolean debug

See Also:

Constant Field Values

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

NONE

public static final byte NONE

See Also:

Constant Field Values

EXPIRATIONSET

public static final byte EXPIRATIONSET

See Also:

Constant Field Values

DELETED

public static final byte DELETED

See Also:

Constant Field Values

LAST

public static final byte LAST

See Also:

Constant Field Values

success

boolean success

status

byte status

newObjectInvid

arlut.csd.ganymede.Invid newObjectInvid

A Serializable Invid that can be returned in response to certain operations on the server.

remoteObjectRef

arlut.csd.ganymede.db_object remoteObjectRef

A remote handle to a db_object on the server returned for use by the client.

rescanList

private java.lang.StringBuffer rescanList

A Serializable StringBuffer representation of objects and fields that need to be rescanned.

dialog

private arlut.csd.JDialog.JDialogBuff dialog

A Serializable Dialog Definition

callback

private arlut.csd.ganymede.Ganymediator callback

A Remote handle to a Wizard object on the server

rescanHash

private transient java.util.Hashtable rescanHash

Maps Invid's to RescanBuf's. Used on the client-side post-serialization.

doNormalProcessing

public boolean doNormalProcessing

This boolean variable is used on the server side only, to determine whether the field code that invoked wizardHook on a DBEditObject subclass should continue with its normal process or whether it should immediately return this ReturnVal to the (client-side) caller.

Constructor Detail

ReturnVal

public ReturnVal(boolean success)

ReturnVal

public ReturnVal(boolean success,
                 boolean doNormalProcessing)

Method Detail

didSucceed

public boolean didSucceed()

This method returns the general success code for the preceding operation. If didSucceed() is true, doRescan() should be checked.

getObjectStatus

public byte getObjectStatus()

Certain operations may set status codes.

getInvid

public arlut.csd.ganymede.Invid getInvid()

This method is used to get an Invid that the server wants to return to the client. Used particularly for invid_field.createNewEmbedded(). Return null if no Invid was set.

See Also:

invid_field, InvidDBField

getObject

public arlut.csd.ganymede.db_object getObject()

This method is used to get a remote db_object reference that the server wants to return to the client. Used particularly for Session.create_db_object() / Session.edit_db_object(), or null if no db_object was returned.

See Also:

Session

getDialog

public arlut.csd.JDialog.JDialogBuff getDialog()

If the operation was not successful, this method should return a dialog box describing the problem and, potentially, asking for more information to complete the operation.

This method should be checked after all calls to the server that return non-null ReturnVal objects.

getDialogText

public java.lang.String getDialogText()

If the operation was not successful, this method should return a the text of any encoded dialog box describing the problem. This method is intended for text-mode clients that do not support the full callback/wizard features that the JDialogBuff class supports.

This method (or getDialog() for GUI clients) should be checked after all calls to the server that return non-null ReturnVal objects.

getCallback

public arlut.csd.ganymede.Ganymediator getCallback()

If the server is asking for more interaction from the user to complete this operation, this method will return an RMI handle to a callback on the server. The client should popup the dialog box specified by getDialog() and pass the results to the callback returned by this method.

This method will return null if getDialog() returns null, and need not be checked in that case.

doRescan

public boolean doRescan()

This method returns true if this ReturnVal encodes rescan information for one or more fields in on or more objects.

This method will never return true if didSucceed() returns false, and need not be checked in that case.

getRescanObjectsList

public java.util.Vector getRescanObjectsList()

This method returns a Vector of Invid objects, corresponding to those objects which need to have some field rescan work done.

rescanAll

public boolean rescanAll(arlut.csd.ganymede.Invid objID)

This method returns true if the server is requesting that all fields in the object referenced by the client's preceding call to the server be reprocessed.

getRescanList

public java.util.Vector getRescanList(arlut.csd.ganymede.Invid objID)

This method returns a Vector of Short() objects if the server provided an explicit list of fields that need to be reprocessed, or null if all or no fields need to be processed.

dumpRescanInfo

public java.lang.String dumpRescanInfo()

This method returns an encoded string representing the objects and fields to be rescanned by the client in response to this ReturnVal.

To be used for debugging.

breakOutRescanList

private void breakOutRescanList()

This private method converts the rescanList StringBuffer to a Hashtable (rescanHash) that maps Invid's to either Vector of Short's or "all".

decodeRescanList

private java.util.Hashtable decodeRescanList(java.lang.StringBuffer buffer,
                                             java.util.Hashtable original)

This method takes a StringBuffer encoded as follows:

263:170|all|271:131|31|57|286:41|all|310:4|134|13|92|

and returns a Hashtable mapping Invid's to the rescan information for that Invid, where the rescan information will either be the String "all", indicating that all fields need to be rescanned, or a Vector of Short's specifying field id's to be rescanned for that object.

Parameters:

buffer - The StringBuffer to be decoded.

original - The Hashtable to put the results into.. this method will put into original the Union of the field rescan information specified in original and the rescan information held in buffer.

Returns:

A reference to original.

clear

public void clear()

unionRescan

public arlut.csd.ganymede.ReturnVal unionRescan(arlut.csd.ganymede.ReturnVal retVal)

unionRescan merges field and object rescan requests from the supplied ReturnVal with and rescan requests we contain.

It is used to allow multiple sources in InvidDBField to contribute rescan requests.

This method returns this so you can do a cascading return.

encodeRescanList

private void encodeRescanList(java.util.Hashtable rescanTable)

This method takes a Hashtable mapping Invid's to Vectors of Short field identifiers or the String "all" and generates the StringBuffer to be serialized down to the client.

For use on the server-side.

setStatus

public void setStatus(byte status)

setRescanAll

public void setRescanAll(arlut.csd.ganymede.Invid objID)

This method makes a note in this ReturnVal to have the client rescan all fields in object objID.

For use on the server-side.

addRescanField

public void addRescanField(arlut.csd.ganymede.Invid objID,
                           short fieldID)

This method makes a note in this ReturnVal to have the client rescan field fieldID in object objID.

For use on the server-side.

setCallback

public void setCallback(arlut.csd.ganymede.Ganymediator callback)

This method attaches a remote reference to a Ganymediator wizard-handler to this ReturnVal for extraction by the client.

For use on the server-side.

setDialog

public void setDialog(arlut.csd.JDialog.JDialogBuff dialog)

This method attaches a dialog definition to this ReturnVal for extraction by the client.

For use on the server-side.

setInvid

public void setInvid(arlut.csd.ganymede.Invid invid)

This method is used to set an Invid that the client can retrieve from us in those cases where a method on the server really does need to return an Invid _and_ a return val.

For use on the server-side.

setObject

public void setObject(arlut.csd.ganymede.db_object object)

This method is used to set a db_object reference that the client can retrieve from us in those cases where a method on the server really does need to return a db_object _and_ a return val.

For use on the server-side.