arlut.csd.ganymede
Class DBField

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

All Implemented Interfaces:

db_field, java.rmi.Remote

Direct Known Subclasses:

BooleanDBField, DateDBField, FloatDBField, InvidDBField, IPDBField, NumericDBField, PasswordDBField, PermissionMatrixDBField, StringDBField

public abstract class DBField

extends java.lang.Object

implements java.rmi.Remote, db_field

This abstract base class encapsulates the basic logic for fields in the Ganymede DBStore, including permissions and unique value handling.

DBFields are the actual carriers of field value in the Ganymede server. Each DBObject holds a set of DBFields in an array. Each DBField is associated with a DBObjectBaseField field definition (see getFieldDef()) by way of its owner's type and it's own field code, which defines the type of the field as well as various generic and type-specific attributes for the field. The DBObjectBaseField information is created and edited with the Ganymede schema editor.

DBField is an abstract class. There is a different subclass of DBField for each kind of data that can be held in the Ganymede server, as follows:

• StringDBField
• BooleanDBField
• NumericDBField
• FloatDBField
• DateDBField
• InvidDBField
• IPDBField
• PasswordDBField
• PermissionMatrixDBField

Each DBField subclass is responsible for writing itself to disk on command with the emit() method, and reading its state in with the receive() method. Each DBField subclass may also have extensive special logic to handle special operations on fields of the appropriate type. For instance, the InvidDBField class has lots and lots of logic for handling the bi-directional object linking that the server depends on for its object handling. Mostly the DBField subclasses provide customization that modifies how things like setValue() and getValue() work, but PasswordDBField and PermissionMatrixDBField don't fit with the standard generic value-container model, and contain their own methods for manipulating and accessing data held in the Ganymede database. Most DBField subclasses only allow a single value to be held, but StringDBField, InvidDBField, and IPDBField support vectors of values.

The Ganymede client can directly access fields in RMI-published objects using the db_field RMI interface. Each concrete subclass of DBField has its own special RMI interface which provides special methods for the client. Adding a new data type to the Ganymede server will involve creating a new DBField subclass, as well as a new RMI interface for any special field methods. All client code would also need to be modified to be aware of the new field type. DBObjectBaseField, DBEditObject and DBObject would also need to be modified to be aware of the new field type for schema editing, customization, and object loading. The schema editor would have to be modified as well.

But you can do it if you absolutely have to. Just be careful and take a good look around at the code.

Note that while DBField was designed to be subclassed, it should only be necessary for adding a new data type to the server. All other likely customizations you'd want to do are handled by DBEditObject customization methods. Most DBField methods at some point call methods on the DBObject/DBEditObject that contains it. All methods that cause changes to fields call out to finalizeXXX() and/or wizardHook() methods in DBEditObject. Consult the DBEditObject customization guide for details on the field/object interactions.

An important note about synchronization: it is possible to encounter a condition called a nested monitor deadlock, where a synchronized method on a field can block trying to enter a synchronized method on a DBSession, GanymedeSession, or DBEditObject object that is itself blocked on another thread trying to call a synchronized method on the same field.

To avoid this condition, no field methods that call synchronized methods on other objects should themselves be synchronized in any fashion.

Field Summary

(package private) short	fieldcode The identifying field number for this field within the owning object.
(package private) DBObject	owner The object this field is contained within
(package private) java.lang.Object	value the object's current value.

Constructor Summary

DBField()

Method Summary

ReturnVal	addElement(java.lang.Object value) Adds an element to the end of this field, if a vector.
ReturnVal	addElement(java.lang.Object submittedValue, boolean local) Adds an element to the end of this field, if a vector.
ReturnVal	addElement(java.lang.Object submittedValue, boolean local, boolean noWizards) Adds an element to the end of this field, if a vector.
ReturnVal	addElementLocal(java.lang.Object value) Adds an element to the end of this field, if a vector.
ReturnVal	addElements(java.util.Vector values) Adds a set of elements to the end of this field, if a vector.
ReturnVal	addElements(java.util.Vector submittedValues, boolean local) Adds a set of elements to the end of this field, if a vector.
ReturnVal	addElements(java.util.Vector submittedValues, boolean local, boolean noWizards) Adds a set of elements to the end of this field, if a vector.
ReturnVal	addElements(java.util.Vector submittedValues, boolean local, boolean noWizards, boolean partialSuccessOk) Adds a set of elements to the end of this field, if a vector.
ReturnVal	addElementsLocal(java.util.Vector values) Adds a set of elements to the end of this field, if a vector.
java.lang.Object	checkpoint() This method is used to basically dump state out of this field so that the DBEditSet checkpoint() code can restore it later if need be.
void	cleanup() This method is intended to be called when this field is being checked into the database.
boolean	containsElement(java.lang.Object value) Returns true if this field is a vector field and value is contained in this field.
boolean	containsElement(java.lang.Object value, boolean local) This method returns true if this field is a vector field and value is contained in this field.
boolean	containsElementLocal(java.lang.Object value) This method returns true if this field is a vector field and value is contained in this field.
ReturnVal	copyFieldTo(DBField target, boolean local) This method copies the current value of this DBField to target.
ReturnVal	deleteAllElements() Removes all elements from this field, if a vector.
ReturnVal	deleteElement(int index) Deletes an element of this field, if a vector.
ReturnVal	deleteElement(int index, boolean local) Deletes an element of this field, if a vector.
ReturnVal	deleteElement(int index, boolean local, boolean noWizards) Deletes an element of this field, if a vector.
ReturnVal	deleteElement(java.lang.Object value) Deletes an element of this field, if a vector.
ReturnVal	deleteElement(java.lang.Object value, boolean local) Deletes an element of this field, if a vector.
ReturnVal	deleteElement(java.lang.Object value, boolean local, boolean noWizards) Deletes an element of this field, if a vector.
ReturnVal	deleteElementLocal(int index) Deletes an element of this field, if a vector.
ReturnVal	deleteElementLocal(java.lang.Object value) Deletes an element of this field, if a vector.
ReturnVal	deleteElements(java.util.Vector values) Removes a set of elements from this field, if a vector.
ReturnVal	deleteElements(java.util.Vector valuesToDelete, boolean local) Removes a set of elements from this field, if a vector.
ReturnVal	deleteElements(java.util.Vector valuesToDelete, boolean local, boolean noWizards) Removes a set of elements from this field, if a vector.
ReturnVal	deleteElementsLocal(java.util.Vector values) Removes a set of elements from this field, if a vector.
(package private) abstract void	emit(java.io.DataOutput out) This method is responsible for writing out the contents of this field to an binary output stream.
(package private) abstract void	emitXML(XMLDumpContext dump) This method is used when the database is being dumped, to write out this field to disk.
boolean	equals(java.lang.Object obj) Returns true if obj is a field with the same value(s) as this one.
java.lang.String	getComment() Returns the description of this field from the schema.
abstract DBField	getCopy(DBObject newOwner) This method is used to return a copy of this field, with the field's owner set to newOwner.
abstract java.lang.String	getDiffString(DBField orig) Returns a String representing the change in value between this field and orig.
java.lang.Object	getElement(int index) Returns the value of an element of this field, if a vector.
abstract java.lang.String	getEncodingString() Returns a String representing a reversible encoding of the value of this field.
DBObjectBaseField	getFieldDef() Returns the DBObjectBaseField for this field.
DBObjectBaseField	getFieldDef(DBObjectBase base) This version of getFieldDef() is intended for use by code sections that need to interrogate a field's type definition before it is linked to an owner object.
DBObjectBaseField	getFieldDef(short objectType) This version of getFieldDef() is intended for use by code sections that need to interrogate a field's type definition before it is linked to an owner object.
FieldInfo	getFieldInfo() Returns a handy field description packet for this field.
FieldTemplate	getFieldTemplate() Returns a handy field description packet for this field, containing the static field elements for this field..
short	getID() Returns the field # for this field.
int	getMaxArraySize() Returns the maximum length of an array in this field type
java.lang.String	getName() Returns the schema name for this field.
DBNameSpace	getNameSpace() Returns the DBNameSpace that this field is associated with, or null if no NameSpace field is associated with this field.
int	getObjTypeID() Returns the object type id for the object containing this field.
DBObject	getOwner() Returns the object this field is part of.
short	getType() Returns the type code for this field from the schema.
java.lang.String	getTypeDesc() Returns the description of this field's type from the schema.
java.lang.Object	getValue() Returns the value of this field, if a scalar.
java.lang.Object	getValue(boolean virtualize) Returns the value of this field, if a scalar.
java.lang.Object	getValueLocal() Returns an Object carrying the value held in this field.
java.util.Vector	getValues() Returns a Vector of the values of the elements in this field, if a vector.
java.util.Vector	getValuesLocal() Returns a Vector of the values of the elements in this field, if a vector.
abstract java.lang.String	getValueString() This method returns a text encoded value for this DBField without checking permissions.
fieldDeltaRec	getVectorDiff(DBField oldField) Returns a fieldDeltaRec object listing the changes between this field's state and that of the prior oldField state.
java.util.Vector	getVectVal() This method is designed to handle casting this field's value into a vector as needed.
java.lang.String	getXMLName() Returns the name for this field, encoded in a form suitable for use as an XML element name.
int	indexOfValue(java.lang.Object value) Sub-class hook to support elements for which the default equals() test is inadequate, such as IP addresses (represented as arrays of Byte[] objects.
boolean	isBuiltIn() This method returns true if this field is one of the system fields present in all objects.
boolean	isDefined() Returns true if this field has a value associated with it, or false if it is an unfilled 'placeholder'.
boolean	isEditable() Returns true if this field is editable, false otherwise.
boolean	isEditable(boolean local) Returns true if this field is editable, false otherwise.
boolean	isEditInPlace() Returns true if this field is edit in place.
boolean	isVector() Returns true if this field is a vector, false otherwise.
boolean	isVisible() Returns true if this field should be displayed in the current client context.
java.lang.Object	key() Object value of DBField.
java.lang.Object	key(int index) Object value of a vector DBField.
(package private) boolean	mark() mark() is used to mark any and all values in this field as taken in the namespace.
(package private) boolean	mark(java.lang.Object value) Mark a specific value associated with this field, rather than mark all values associated with this field.
(package private) abstract void	receive(java.io.DataInput in, DBObjectBaseField definition) This method is responsible for reading in the contents of this field from an binary input stream.
ReturnVal	rescanThisField(ReturnVal original) This method takes the result of an operation on this field and wraps it with a ReturnVal that encodes an instruction to the client to rescan this field.
void	rollback(java.lang.Object oldval) This method is used to basically force state into this field.
ReturnVal	setElement(int index, java.lang.Object value) Sets the value of an element of this field, if a vector.
ReturnVal	setElement(int index, java.lang.Object submittedValue, boolean local) Sets the value of an element of this field, if a vector.
ReturnVal	setElement(int index, java.lang.Object submittedValue, boolean local, boolean noWizards) Sets the value of an element of this field, if a vector.
ReturnVal	setElementLocal(int index, java.lang.Object value) Sets the value of an element of this field, if a vector.
(package private) void	setOwner(DBObject owner) Package-domain method to set the owner of this field.
ReturnVal	setUndefined(boolean local) This method is used to mark a field as undefined when it is checked out for editing.
ReturnVal	setValue(java.lang.Object value) Sets the value of this field, if a scalar.
ReturnVal	setValue(java.lang.Object submittedValue, boolean local) Sets the value of this field, if a scalar.
ReturnVal	setValue(java.lang.Object submittedValue, boolean local, boolean noWizards) Sets the value of this field, if a scalar.
ReturnVal	setValueLocal(java.lang.Object value) Sets the value of this field, if a scalar.
int	size() Returns number of elements in vector if this is a vector field.
java.lang.String	toString() For debugging
(package private) boolean	unmark() unmark() is used to make any and all namespace values in this field as available for use by other objects in the same editset.
(package private) boolean	unmark(java.lang.Object value) Unmark a specific value associated with this field, rather than unmark all values associated with this field.
abstract ReturnVal	verifyNewValue(java.lang.Object o) Overridable method to verify that an object submitted to this field has an appropriate value.
boolean	verifyReadPermission() Overridable method to verify that the current DBSession / DBEditSet has permission to read values from this field.
abstract boolean	verifyTypeMatch(java.lang.Object o) Overridable method to determine whether an Object submitted to this field is of an appropriate type.
boolean	verifyWritePermission() Overridable method to verify that the current DBSession / DBEditSet has permission to write values into this field.

Methods inherited from class java.lang.Object

, clone, finalize, getClass, hashCode, notify, notifyAll, registerNatives, wait, wait, wait

Field Detail

value

java.lang.Object value

the object's current value. May be a Vector for vector fields, in which case getVectVal() may be used to perform the cast.

owner

DBObject owner

The object this field is contained within

fieldcode

short fieldcode

The identifying field number for this field within the owning object. This number is an index into the owning object type's field dictionary.

Constructor Detail

DBField

public DBField()

Method Detail

getCopy

public abstract DBField getCopy(DBObject newOwner)

This method is used to return a copy of this field, with the field's owner set to newOwner.

getVectVal

public final java.util.Vector getVectVal()

This method is designed to handle casting this field's value into a vector as needed. We don't bother to check whether value is a Vector here, as the code which would have used the old values field should do that for us themselves.

This method does no permissions checking at all, and should only be used from within DBField and subclass code. For other purposes, use getValuesLocal().

key

public java.lang.Object key()

Object value of DBField. Used to represent value in value hashes. Subclasses need to override this method in subclass.

key

public java.lang.Object key(int index)

Object value of a vector DBField. Used to represent value in value hashes. Subclasses need to override this method in subclass.

size

public int size()

Returns number of elements in vector if this is a vector field. If this is not a vector field, will return 1. (Should throw exception?)

Specified by:

size in interface db_field

getMaxArraySize

public int getMaxArraySize()

Returns the maximum length of an array in this field type

emit

abstract void emit(java.io.DataOutput out)
            throws java.io.IOException

This method is responsible for writing out the contents of this field to an binary output stream. It is used in writing fields to the ganymede.db file and to the journal file.

This method only writes out the value contents of this field. The DBObject emit() method is responsible for writing out the field identifier information ahead of the field's contents.

receive

abstract void receive(java.io.DataInput in,
                      DBObjectBaseField definition)
               throws java.io.IOException

This method is responsible for reading in the contents of this field from an binary input stream. It is used in reading fields from the ganymede.db file and from the journal file.

The code that calls receive() on this field is responsible for having read enough of the binary input stream's context to place the read cursor at the point in the file immediately after the field's id and type information has been read.

emitXML

abstract void emitXML(XMLDumpContext dump)
               throws java.io.IOException

This method is used when the database is being dumped, to write out this field to disk. It is mated with receiveXML().

equals

public boolean equals(java.lang.Object obj)

Returns true if obj is a field with the same value(s) as this one.

This method is ok to be synchronized because it does not call synchronized methods on any other object that is likely to have another thread trying to call another synchronized method on us.

Overrides:

equals in class java.lang.Object

copyFieldTo

public ReturnVal copyFieldTo(DBField target,
                             boolean local)

This method copies the current value of this DBField to target. The target DBField must be contained within a checked-out DBEditObject in order to be updated. Any actions that would normally occur from a user manually setting a value into the field will occur.

Parameters:

target - The DBField to copy this field's contents to.

local - If true, permissions checking is skipped.

cleanup

public void cleanup()

This method is intended to be called when this field is being checked into the database. Subclasses of DBField will override this method to clean up data that is cached for speed during editing.

getFieldTemplate

public final FieldTemplate getFieldTemplate()

Returns a handy field description packet for this field, containing the static field elements for this field..

Specified by:

getFieldTemplate in interface db_field

See Also:

db_field

getFieldInfo

public final FieldInfo getFieldInfo()

Returns a handy field description packet for this field.

Specified by:

getFieldInfo in interface db_field

See Also:

db_field

getName

public final java.lang.String getName()

Returns the schema name for this field.

Specified by:

getName in interface db_field

See Also:

db_field

getXMLName

public final java.lang.String getXMLName()

Returns the name for this field, encoded in a form suitable for use as an XML element name.

getID

public final short getID()

Returns the field # for this field.

Specified by:

getID in interface db_field

See Also:

db_field

getOwner

public final DBObject getOwner()

Returns the object this field is part of.

getComment

public final java.lang.String getComment()

Returns the description of this field from the schema.

Specified by:

getComment in interface db_field

See Also:

db_field

getTypeDesc

public final java.lang.String getTypeDesc()

Returns the description of this field's type from the schema.

Specified by:

getTypeDesc in interface db_field

See Also:

db_field

getType

public final short getType()

Returns the type code for this field from the schema.

Specified by:

getType in interface db_field

See Also:

db_field

getValueString

public abstract java.lang.String getValueString()

This method returns a text encoded value for this DBField without checking permissions.

This method avoids checking permissions because it is used on the server side only and because it is involved in the getLabel() logic for DBObject, which is invoked from GanymedeSession's getPerm() method.

If this method checked permissions and the getPerm() method failed for some reason and tried to report the failure using object.getLabel(), as it does at present, the server could get into an infinite loop.

Specified by:

getValueString in interface db_field

getEncodingString

public abstract java.lang.String getEncodingString()

Returns a String representing a reversible encoding of the value of this field. Each field type will have its own encoding, suitable for embedding in a DumpResult.

Specified by:

getEncodingString in interface db_field

See Also:

db_field

getDiffString

public abstract java.lang.String getDiffString(DBField orig)

Returns a String representing the change in value between this field and orig. This String is intended for logging and email, not for any sort of programmatic activity. The format of the generated string is not defined, but is intended to be suitable for inclusion in a log entry and in an email message.

If there is no change in the field, null will be returned.

isDefined

public boolean isDefined()

Returns true if this field has a value associated with it, or false if it is an unfilled 'placeholder'.

Specified by:

isDefined in interface db_field

See Also:

db_field

setUndefined

public ReturnVal setUndefined(boolean local)

This method is used to mark a field as undefined when it is checked out for editing. Different subclasses of DBField may implement this in different ways, if simply setting the field's value member to null is not appropriate. Any namespace values claimed by the field will be released, and when the transaction is committed, this field will be released.

isVector

public final boolean isVector()

Returns true if this field is a vector, false otherwise.

Specified by:

isVector in interface db_field

See Also:

db_field

isEditable

public final boolean isEditable()

Returns true if this field is editable, false otherwise.

Note that DBField are only editable if they are contained in a subclass of DBEditObject.

Specified by:

isEditable in interface db_field

See Also:

db_field

isEditable

public final boolean isEditable(boolean local)

Returns true if this field is editable, false otherwise.

Note that DBField are only editable if they are contained in a subclass of DBEditObject.

Server-side method only

*Deadlock Hazard.*

Parameters:

local - If true, skip permissions checking

isBuiltIn

public final boolean isBuiltIn()

This method returns true if this field is one of the system fields present in all objects.

Specified by:

isBuiltIn in interface db_field

isVisible

public final boolean isVisible()

Returns true if this field should be displayed in the current client context.

Specified by:

isVisible in interface db_field

See Also:

db_field

isEditInPlace

public final boolean isEditInPlace()

Returns true if this field is edit in place.

Specified by:

isEditInPlace in interface db_field

getObjTypeID

public final int getObjTypeID()

Returns the object type id for the object containing this field.

getNameSpace

public final DBNameSpace getNameSpace()

Returns the DBNameSpace that this field is associated with, or null if no NameSpace field is associated with this field.

getFieldDef

public final DBObjectBaseField getFieldDef()

Returns the DBObjectBaseField for this field.

getFieldDef

public final DBObjectBaseField getFieldDef(short objectType)

This version of getFieldDef() is intended for use by code sections that need to interrogate a field's type definition before it is linked to an owner object.

getFieldDef

public final DBObjectBaseField getFieldDef(DBObjectBase base)

This version of getFieldDef() is intended for use by code sections that need to interrogate a field's type definition before it is linked to an owner object.

getValue

public java.lang.Object getValue()

Returns the value of this field, if a scalar. An IllegalArgumentException will be thrown if this field is a vector.

Specified by:

getValue in interface db_field

See Also:

db_field

getValue

public java.lang.Object getValue(boolean virtualize)

Returns the value of this field, if a scalar. This method is intended to be used by the virtualizing hook to use to return the default value if the virtualizer wants to pass through.

See Also:

db_field

setValue

public final ReturnVal setValue(java.lang.Object value)

Sets the value of this field, if a scalar.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

This method is intended to be called by code that needs to go through the permission checking regime, and that needs to have rescan information passed back. This includes most wizard setValue calls.

Specified by:

setValue in interface db_field

See Also:

DBSession, db_field

setValueLocal

public final ReturnVal setValueLocal(java.lang.Object value)

Sets the value of this field, if a scalar.

This method is server-side only, and bypasses permissions checking.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

setValue

public final ReturnVal setValue(java.lang.Object submittedValue,
                                boolean local)

Sets the value of this field, if a scalar.

This method is server-side only.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

Parameters:

value - Value to set this field to

local - If true, permissions checking will be skipped

setValue

public ReturnVal setValue(java.lang.Object submittedValue,
                          boolean local,
                          boolean noWizards)

Sets the value of this field, if a scalar.

This method is server-side only.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

This method will be overridden by DBField subclasses with special needs.

Parameters:

value - Value to set this field to

local - If true, permissions checking will be skipped

noWizards - If true, wizards will be skipped

getValues

public java.util.Vector getValues()

Returns a Vector of the values of the elements in this field, if a vector.

This is only valid for vectors. If the field is a scalar, use getValue().

This method checks for read permissions.

Be very careful using this for server-side code, because the Vector returned is not cloned from the field's actual data Vector, for performance reasons. If this is called by the client, the serialization process will protect us from the client being able to mess with our contents.

Specified by:

getValues in interface db_field

See Also:

db_field

getElement

public java.lang.Object getElement(int index)

Returns the value of an element of this field, if a vector.

Specified by:

getElement in interface db_field

See Also:

db_field

setElement

public final ReturnVal setElement(int index,
                                  java.lang.Object value)

Sets the value of an element of this field, if a vector.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

The ReturnVal resulting from a successful setElement will encode an order to rescan this field.

Specified by:

setElement in interface db_field

See Also:

DBSession, db_field

setElementLocal

public final ReturnVal setElementLocal(int index,
                                       java.lang.Object value)

Sets the value of an element of this field, if a vector.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

See Also:

DBSession

setElement

public final ReturnVal setElement(int index,
                                  java.lang.Object submittedValue,
                                  boolean local)

Sets the value of an element of this field, if a vector.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. A null result means the operation was carried out successfully and no information needed to be passed back about side-effects.

setElement

public ReturnVal setElement(int index,
                            java.lang.Object submittedValue,
                            boolean local,
                            boolean noWizards)

Sets the value of an element of this field, if a vector.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. A null result means the operation was carried out successfully and no information needed to be passed back about side-effects.

addElement

public final ReturnVal addElement(java.lang.Object value)

Adds an element to the end of this field, if a vector.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

The ReturnVal resulting from a successful addElement will encode an order to rescan this field.

Specified by:

addElement in interface db_field

See Also:

db_field

addElementLocal

public final ReturnVal addElementLocal(java.lang.Object value)

Adds an element to the end of this field, if a vector.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

addElement

public final ReturnVal addElement(java.lang.Object submittedValue,
                                  boolean local)

Adds an element to the end of this field, if a vector.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

Parameters:

submittedValue - Value to be added

local - If true, permissions checking will be skipped

addElement

public ReturnVal addElement(java.lang.Object submittedValue,
                            boolean local,
                            boolean noWizards)

Adds an element to the end of this field, if a vector.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

Parameters:

submittedValue - Value to be added

local - If true, permissions checking will be skipped

noWizards - If true, wizards will be skipped

addElements

public final ReturnVal addElements(java.util.Vector values)

Adds a set of elements to the end of this field, if a vector. Using addElements() to add a sequence of items to a field may be many times more efficient than calling addElement() repeatedly, as addElements() can do a single server checkpoint before attempting to add all the values.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all values were added. If failure is returned, no values were added.

The ReturnVal resulting from a successful addElements will encode an order to rescan this field.

Specified by:

addElements in interface db_field

See Also:

db_field

addElementsLocal

public final ReturnVal addElementsLocal(java.util.Vector values)

Adds a set of elements to the end of this field, if a vector. Using addElements() to add a sequence of items to a field may be many times more efficient than calling addElement() repeatedly, as addElements() can do a single server checkpoint before attempting to add all the values.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all values were added. If failure is returned, no values were added.

addElements

public final ReturnVal addElements(java.util.Vector submittedValues,
                                   boolean local)

Adds a set of elements to the end of this field, if a vector. Using addElements() to add a sequence of items to a field may be many times more efficient than calling addElement() repeatedly, as addElements() can do a single server checkpoint before attempting to add all the values.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all values were added. If failure is returned, no values were added.

Parameters:

submittedValues - Values to be added

local - If true, permissions checking will be skipped

addElements

public final ReturnVal addElements(java.util.Vector submittedValues,
                                   boolean local,
                                   boolean noWizards)

Adds a set of elements to the end of this field, if a vector. Using addElements() to add a sequence of items to a field may be many times more efficient than calling addElement() repeatedly, as addElements() can do a single server checkpoint before attempting to add all the values.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all values were added. If failure is returned, no values were added.

Parameters:

submittedValues - Values to be added

local - If true, permissions checking will be skipped

noWizards - If true, wizards will be skipped

addElements

public ReturnVal addElements(java.util.Vector submittedValues,
                             boolean local,
                             boolean noWizards,
                             boolean partialSuccessOk)

Adds a set of elements to the end of this field, if a vector. Using addElements() to add a sequence of items to a field may be many times more efficient than calling addElement() repeatedly, as addElements() can do a single server checkpoint before attempting to add all the values.

Server-side method only

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all values were added. If failure is returned, no values were added.

Parameters:

submittedValues - Values to be added

local - If true, permissions checking will be skipped

noWizards - If true, wizards will be skipped

partialSuccessOk - If true, addElements will add any values that it can, even if some values are refused by the server logic. Any values that are skipped will be reported in a dialog passed back in the returned ReturnVal

deleteElement

public final ReturnVal deleteElement(int index)

Deletes an element of this field, if a vector.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

Specified by:

deleteElement in interface db_field

See Also:

db_field

deleteElementLocal

public final ReturnVal deleteElementLocal(int index)

Deletes an element of this field, if a vector.

Server-side method only

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

deleteElement

public final ReturnVal deleteElement(int index,
                                     boolean local)

Deletes an element of this field, if a vector.

Server-side method only

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

deleteElement

public ReturnVal deleteElement(int index,
                               boolean local,
                               boolean noWizards)

Deletes an element of this field, if a vector.

Server-side method only

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

deleteElement

public final ReturnVal deleteElement(java.lang.Object value)

Deletes an element of this field, if a vector.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog.

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

Specified by:

deleteElement in interface db_field

See Also:

db_field

deleteElementLocal

public final ReturnVal deleteElementLocal(java.lang.Object value)

Deletes an element of this field, if a vector.

Server-side method only

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

deleteElement

public final ReturnVal deleteElement(java.lang.Object value,
                                     boolean local)

Deletes an element of this field, if a vector.

Server-side method only

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

deleteElement

public ReturnVal deleteElement(java.lang.Object value,
                               boolean local,
                               boolean noWizards)

Deletes an element of this field, if a vector.

Server-side method only

The ReturnVal resulting from a successful deleteElement will encode an order to rescan this field.

deleteAllElements

public ReturnVal deleteAllElements()

Removes all elements from this field, if a vector.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all elements in values was removed from this field. If a failure code is returned, no elements in values were removed.

The ReturnVal resulting from a successful deleteAllElements will encode an order to rescan this field.

Specified by:

deleteAllElements in interface db_field

See Also:

db_field

deleteElements

public final ReturnVal deleteElements(java.util.Vector values)

Removes a set of elements from this field, if a vector. Using deleteElements() to remove a sequence of items from a field may be many times more efficient than calling deleteElement() repeatedly, as removeElements() can do a single server checkpoint before attempting to remove all the values.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all elements in values was removed from this field. If a failure code is returned, no elements in values were removed.

The ReturnVal resulting from a successful deleteElements will encode an order to rescan this field.

Specified by:

deleteElements in interface db_field

See Also:

db_field

deleteElementsLocal

public final ReturnVal deleteElementsLocal(java.util.Vector values)

Removes a set of elements from this field, if a vector. Using deleteElements() to remove a sequence of items from a field may be many times more efficient than calling deleteElement() repeatedly, as removeElements() can do a single server checkpoint before attempting to remove all the values.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all elements in values was removed from this field. If a failure code is returned, no elements in values were removed.

Server-side method only

deleteElements

public final ReturnVal deleteElements(java.util.Vector valuesToDelete,
                                      boolean local)

Removes a set of elements from this field, if a vector. Using deleteElements() to remove a sequence of items from a field may be many times more efficient than calling deleteElement() repeatedly, as removeElements() can do a single server checkpoint before attempting to remove all the values.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all elements in values was removed from this field. If a failure code is returned, no elements in values were removed.

Server-side method only

deleteElements

public ReturnVal deleteElements(java.util.Vector valuesToDelete,
                                boolean local,
                                boolean noWizards)

Removes a set of elements from this field, if a vector. Using deleteElements() to remove a sequence of items from a field may be many times more efficient than calling deleteElement() repeatedly, as removeElements() can do a single server checkpoint before attempting to remove all the values.

The ReturnVal object returned encodes success or failure, and may optionally pass back a dialog. If a success code is returned, all elements in values was removed from this field. If a failure code is returned, no elements in values were removed.

Server-side method only

containsElement

public final boolean containsElement(java.lang.Object value)

Returns true if this field is a vector field and value is contained in this field.

This method always checks for read privileges.

Specified by:

containsElement in interface db_field

Parameters:

value - The value to look for in this field

See Also:

db_field

containsElementLocal

public final boolean containsElementLocal(java.lang.Object value)

This method returns true if this field is a vector field and value is contained in this field.

This method is server-side only, and never checks for read privileges.

Parameters:

value - The value to look for in this fieldu

containsElement

public boolean containsElement(java.lang.Object value,
                               boolean local)

This method returns true if this field is a vector field and value is contained in this field.

This method is server-side only.

Parameters:

value - The value to look for in this field

local - If false, read permissin is checked for this field

getVectorDiff

public fieldDeltaRec getVectorDiff(DBField oldField)

Returns a fieldDeltaRec object listing the changes between this field's state and that of the prior oldField state.

setOwner

void setOwner(DBObject owner)

Package-domain method to set the owner of this field.

Used by the DBObject copy constructor.

unmark

boolean unmark()

unmark() is used to make any and all namespace values in this field as available for use by other objects in the same editset. When the editset is committed, any unmarked values will be flushed from the namespace.

*Calls synchronized methods on DBNameSpace*

unmark

boolean unmark(java.lang.Object value)

Unmark a specific value associated with this field, rather than unmark all values associated with this field. Note that this method does not check to see if the value is currently associated with this field, it just goes ahead and unmarks it. This is to be used by the vector modifiers (setElement, addElement, deleteElement, etc.) to keep track of namespace modifications as we go along.

*Calls synchronized methods on DBNameSpace*

mark

boolean mark()

mark() is used to mark any and all values in this field as taken in the namespace. When the editset is committed, marked values will be permanently reserved in the namespace. If the editset is instead aborted, the namespace values will be returned to their pre-editset status.

*Calls synchronized methods on DBNameSpace*

mark

boolean mark(java.lang.Object value)

Mark a specific value associated with this field, rather than mark all values associated with this field. Note that this method does not in any way associate this value with this field (add it, set it, etc.), it just marks it. This is to be used by the vector modifiers (setElement, addElement, etc.) to keep track of namespace modifications as we go along.

*Calls synchronized methods on DBNameSpace*

verifyTypeMatch

public abstract boolean verifyTypeMatch(java.lang.Object o)

Overridable method to determine whether an Object submitted to this field is of an appropriate type.

verifyNewValue

public abstract ReturnVal verifyNewValue(java.lang.Object o)

Overridable method to verify that an object submitted to this field has an appropriate value.

verifyReadPermission

public boolean verifyReadPermission()

Overridable method to verify that the current DBSession / DBEditSet has permission to read values from this field.

verifyWritePermission

public boolean verifyWritePermission()

Overridable method to verify that the current DBSession / DBEditSet has permission to write values into this field.

indexOfValue

public int indexOfValue(java.lang.Object value)

Sub-class hook to support elements for which the default equals() test is inadequate, such as IP addresses (represented as arrays of Byte[] objects.

Returns -1 if the value was not found in this field.

This method assumes that the calling method has already verified that this is a vector field.

getValuesLocal

public java.util.Vector getValuesLocal()

Returns a Vector of the values of the elements in this field, if a vector.

This is intended to be used within the Ganymede server, it bypasses the permissions checking that getValues() does.

The server code *must not* make any modifications to the returned vector as doing such may violate the namespace maintenance logic. Always, always, use the addElement(), deleteElement(), setElement() methods in this class.

Remember, this method gives you *direct access to the vector from this field. Always always clone the Vector returned if you find you need to modify the results you get back. I'm trusting you here. Pay attention.

getValueLocal

public java.lang.Object getValueLocal()

Returns an Object carrying the value held in this field.

This is intended to be used within the Ganymede server, it bypasses the permissions checking that getValues() does.

checkpoint

public java.lang.Object checkpoint()

This method is used to basically dump state out of this field so that the DBEditSet checkpoint() code can restore it later if need be.

This method is not synchronized because all operations performed by this method are either synchronized at a lower level or are atomic.

Called by DBEditObject's checkpoint() method.

rollback

public void rollback(java.lang.Object oldval)

This method is used to basically force state into this field.

It is used to place a value or set of values that were known to be good during the current transaction back into this field, without creating or changing this DBField's object identity, and without doing any of the checking or side effects that calling setValue() will typically do.

In particular, it is not necessary to subclass this method for use with InvidDBField, since the rollback() method will always rollback all objects in the transaction at the same time. It is not necessary to have the InvidDBField subclass handle binding/unbinding during rollback, since all objects which could conceivably be involved in a link will also have their own states rolled back.

Called by DBEditObject's rollback() method.

rescanThisField

public final ReturnVal rescanThisField(ReturnVal original)

This method takes the result of an operation on this field and wraps it with a ReturnVal that encodes an instruction to the client to rescan this field. This isn't normally necessary for most client operations, but it is necessary for the case in which wizards call DBField.setValue() on behalf of the client, because in those cases, the client otherwise won't know that the wizard modified the field.

This makes for a significant bit of overhead on client calls to the field modifier methods, but this is avoided if code on the server uses setValueLocal(), setElementLocal(), addElementLocal(), or deleteElementLocal() to make changes to a field.

If you are ever in a situation where you want to use the local variants of the modifier methods (to avoid permissions checking overhead), but you do want to have the field's rescan information returned, you can do something like:

 return field.rescanThisField(field.setValueLocal(null));

 

toString

public java.lang.String toString()

For debugging

Overrides:

toString in class java.lang.Object