arlut.csd.ganymede
Class IPDBField

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

All Implemented Interfaces:

db_field, ip_field, java.rmi.Remote

public class IPDBField

extends DBField

implements ip_field

IPDBField is a subclass of DBField for the storage and handling of IPv4/IPv6 address fields in the DBStore on the Ganymede server.

The Ganymede client talks to IPDBFields through the ip_field RMI interface.

Note that wherever Ganymede manipulates IP addresses, it does so in terms of unsigned byte arrays. Since Java does not provide an unsigned byte type, Ganymede uses the s2u() and u2s() static methods defined in this class to convert from the signed Java byte to the Ganymede 0-255 IP octet range.

Field Summary

(package private) static boolean	debug
private static java.lang.String	IPv4allowedChars
private static java.lang.String	IPv6allowedChars

Fields inherited from class arlut.csd.ganymede.DBField

fieldcode, owner, value

Constructor Summary

(package private)	IPDBField(arlut.csd.ganymede.DBObject owner, java.io.DataInput in, arlut.csd.ganymede.DBObjectBaseField definition) Receive constructor.
	IPDBField(arlut.csd.ganymede.DBObject owner, java.util.Date value, arlut.csd.ganymede.DBObjectBaseField definition) Scalar value constructor.
(package private)	IPDBField(arlut.csd.ganymede.DBObject owner, arlut.csd.ganymede.DBObjectBaseField definition) No-value constructor.
	IPDBField(arlut.csd.ganymede.DBObject owner, arlut.csd.ganymede.IPDBField field) Copy constructor.
	IPDBField(arlut.csd.ganymede.DBObject owner, java.util.Vector values, arlut.csd.ganymede.DBObjectBaseField definition) Vector value constructor.

Method Summary

arlut.csd.ganymede.ReturnVal	addElement(java.lang.Object value, boolean local, boolean noWizards) Adds an element to the end of this field, if a vector.
java.lang.Object	clone()
(package private) void	emit(java.io.DataOutput out) This method is responsible for writing out the contents of this field to an binary output stream.
void	emitIPXML(arlut.csd.ganymede.XMLDumpContext xmlOut, java.lang.Byte[] value)
(package private) void	emitXML(arlut.csd.ganymede.XMLDumpContext xmlOut) This method is used when the database is being dumped, to write out this field to disk.
private boolean	equalTest(java.lang.Byte[] localBytes, java.lang.Byte[] foreignBytes) Equality test.
static java.lang.String	genIPString(java.lang.Byte[] octets)
static java.lang.Byte[]	genIPV4bytes(java.lang.String input) This method takes an IPv4 string in standard format and generates an array of 4 bytes that the Ganymede server can accept.
static java.lang.String	genIPV4string(java.lang.Byte[] octets) This method generates a standard string representation of an IPv4 address from an array of 4 octets.
static java.lang.Byte[]	genIPV6bytes(java.lang.String input) This method takes an IPv6 string in any of the standard RFC 1884 formats or a standard IPv4 string and generates an array of 16 bytes that the Ganymede server can accept as an IPv6 address.
static java.lang.String	genIPV6string(java.lang.Byte[] octets) This method takes an array of 4 or 16 bytes and generates an optimal RFC 1884 string encoding suitable for display.
arlut.csd.ganymede.DBField	getCopy(arlut.csd.ganymede.DBObject newOwner) This method is used to return a copy of this field, with the field's owner set to newOwner.
java.lang.String	getDiffString(arlut.csd.ganymede.DBField orig) Returns a String representing the change in value between this field and orig.
java.lang.String	getEncodingString() The normal getValueString() encoding of IP addresses is acceptable.
java.lang.String	getValueString() Returns a String representing the value of this field.
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.
private static boolean	isAllowedV4(char ch) determines whether a given character is valid or invalid for a JIPField
private static boolean	isAllowedV6(char ch) determines whether a given character is valid or invalid for a JIPField
boolean	isIPV4() Returns true if the value stored in this IP field is an IPV4 address.
boolean	isIPV4(short index) Returns true if the value stored in the given element of this IP field is an IPV4 address, if no value is set, this method will return false.
boolean	isIPV6() Returns true if the value stored in this IP field is an IPV6 address.
boolean	isIPV6(short index) Returns true if the value stored in the given element of this IP field is an IPV6 address.
static void	main(java.lang.String[] argv) Test rig
(package private) void	receive(java.io.DataInput in, arlut.csd.ganymede.DBObjectBaseField definition) This method is responsible for reading in the contents of this field from an binary input stream.
static short	s2u(byte b) This method maps a u2s-encoded signed byte value to an int value between 0 and 255 inclusive.
arlut.csd.ganymede.ReturnVal	setElement(int index, java.lang.Object value, boolean local, boolean noWizards) Sets the value of this field, if a vector.
arlut.csd.ganymede.ReturnVal	setValue(java.lang.Object value, boolean local, boolean noWizards) Sets the value of this field, if a scalar.
static byte	u2s(int x) This method maps an int value between 0 and 255 inclusive to a legal signed byte value.
boolean	v6Allowed() Returns true if this field is permitted to hold IPv6 addresses.
java.lang.Byte[]	value()
java.lang.Byte[]	value(int index)
arlut.csd.ganymede.ReturnVal	verifyNewValue(java.lang.Object o) Overridable method to verify that an object submitted to this field has an appropriate value.
boolean	verifyTypeMatch(java.lang.Object o) Overridable method to determine whether an Object submitted to this field is of an appropriate type.

Methods inherited from class arlut.csd.ganymede.DBField

addElement, addElement, addElementLocal, addElements, addElements, addElements, addElements, addElementsLocal, checkpoint, cleanup, containsElement, containsElement, containsElementLocal, copyFieldTo, deleteAllElements, deleteElement, deleteElement, deleteElement, deleteElement, deleteElement, deleteElement, deleteElementLocal, deleteElementLocal, deleteElements, deleteElements, deleteElements, deleteElementsLocal, equals, getComment, getElement, getFieldDef, getFieldDef, getFieldDef, getFieldInfo, getFieldTemplate, getID, getMaxArraySize, getName, getNameSpace, getObjTypeID, getOwner, getType, getTypeDesc, getValue, getValue, getValueLocal, getValues, getValuesLocal, getVectorDiff, getVectVal, getXMLName, isBuiltIn, isDefined, isEditable, isEditable, isEditInPlace, isVector, isVisible, key, key, mark, mark, rescanThisField, rollback, setElement, setElement, setElementLocal, setOwner, setUndefined, setValue, setValue, setValueLocal, size, toString, unmark, unmark, verifyReadPermission, verifyWritePermission

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface arlut.csd.ganymede.db_field

addElement, addElements, containsElement, deleteAllElements, deleteElement, deleteElement, deleteElements, getComment, getElement, getFieldInfo, getFieldTemplate, getID, getName, getType, getTypeDesc, getValue, getValues, isBuiltIn, isDefined, isEditable, isEditInPlace, isVector, isVisible, setElement, setValue, size

Field Detail

debug

static final boolean debug

See Also:

Constant Field Values

IPv4allowedChars

private static java.lang.String IPv4allowedChars

IPv6allowedChars

private static java.lang.String IPv6allowedChars

Constructor Detail

IPDBField

IPDBField(arlut.csd.ganymede.DBObject owner,
          java.io.DataInput in,
          arlut.csd.ganymede.DBObjectBaseField definition)
    throws java.io.IOException

Receive constructor. Used to create a IPDBField from a DBStore/DBJournal DataInput stream.

IPDBField

IPDBField(arlut.csd.ganymede.DBObject owner,
          arlut.csd.ganymede.DBObjectBaseField definition)

No-value constructor. Allows the construction of a 'non-initialized' field, for use where the DBObjectBase definition indicates that a given field may be present, but for which no value has been stored in the DBStore.

Used to provide the client a template for 'creating' this field if so desired.

IPDBField

public IPDBField(arlut.csd.ganymede.DBObject owner,
                 arlut.csd.ganymede.IPDBField field)

Copy constructor.

IPDBField

public IPDBField(arlut.csd.ganymede.DBObject owner,
                 java.util.Date value,
                 arlut.csd.ganymede.DBObjectBaseField definition)

Scalar value constructor.

IPDBField

public IPDBField(arlut.csd.ganymede.DBObject owner,
                 java.util.Vector values,
                 arlut.csd.ganymede.DBObjectBaseField definition)

Vector value constructor.

Method Detail

getCopy

public arlut.csd.ganymede.DBField getCopy(arlut.csd.ganymede.DBObject newOwner)

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

Specified by:

getCopy in class DBField

clone

public java.lang.Object clone()

Overrides:

clone in class java.lang.Object

emit

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

Description copied from class: DBField

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.

Specified by:

emit in class DBField

java.io.IOException

receive

void receive(java.io.DataInput in,
             arlut.csd.ganymede.DBObjectBaseField definition)
       throws java.io.IOException

Description copied from class: DBField

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.

Specified by:

receive in class DBField

java.io.IOException

emitXML

void emitXML(arlut.csd.ganymede.XMLDumpContext xmlOut)
       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().

Specified by:

emitXML in class DBField

java.io.IOException

emitIPXML

public void emitIPXML(arlut.csd.ganymede.XMLDumpContext xmlOut,
                      java.lang.Byte[] value)
               throws java.io.IOException

java.io.IOException

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.

Overrides:

indexOfValue in class DBField

equalTest

private boolean equalTest(java.lang.Byte[] localBytes,
                          java.lang.Byte[] foreignBytes)

Equality test.

setValue

public arlut.csd.ganymede.ReturnVal setValue(java.lang.Object value,
                                             boolean local,
                                             boolean noWizards)

Sets the value of this field, if a scalar.

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

Note that IPDBField needs its own setValue() method (rather than using DBField.setValue() because it needs to be able to accept either a Byte[] array or a String with IP information in either IPv4 or IPv6 encoding.

Overrides:

setValue in class DBField

Parameters:

local - If true, permissions checking will be skipped

noWizards - If true, wizards will be skipped

setElement

public arlut.csd.ganymede.ReturnVal setElement(int index,
                                               java.lang.Object value,
                                               boolean local,
                                               boolean noWizards)

Sets the value of this field, if a vector.

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

Note that IPDBField needs its own setElement() method (rather than using DBField.setElement() because it needs to be able to accept either a Byte[] array or a String with IP information in either IPv4 or IPv6 encoding.

Overrides:

setElement in class DBField

addElement

public arlut.csd.ganymede.ReturnVal addElement(java.lang.Object value,
                                               boolean local,
                                               boolean noWizards)

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.

Note that IPDBField needs its own addElement() method (rather than using DBField.addElement() because it needs to be able to accept either a Byte[] array or a String with IP information in either IPv4 or IPv6 encoding.

Overrides:

addElement in class DBField

Parameters:

value - Value to be added

local - If true, permissions checking will be skipped

noWizards - If true, wizards will be skipped

value

public java.lang.Byte[] value()

value

public java.lang.Byte[] value(int index)

getValueString

public java.lang.String getValueString()

Description copied from interface: db_field

Returns a String representing the value of this field.

Specified by:

getValueString in interface db_field

Specified by:

getValueString in class DBField

getEncodingString

public java.lang.String getEncodingString()

The normal getValueString() encoding of IP addresses is acceptable.

Specified by:

getEncodingString in interface db_field

Specified by:

getEncodingString in class DBField

See Also:

db_field

getDiffString

public java.lang.String getDiffString(arlut.csd.ganymede.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.

Specified by:

getDiffString in class DBField

v6Allowed

public boolean v6Allowed()

Returns true if this field is permitted to hold IPv6 addresses.

Specified by:

v6Allowed in interface ip_field

isIPV4

public boolean isIPV4()

Returns true if the value stored in this IP field is an IPV4 address. If no value has been set for this field, false is returned.

Specified by:

isIPV4 in interface ip_field

See Also:

ip_field

isIPV4

public boolean isIPV4(short index)

Returns true if the value stored in the given element of this IP field is an IPV4 address, if no value is set, this method will return false.

Specified by:

isIPV4 in interface ip_field

Parameters:

index - Array index for the value to be checked

See Also:

ip_field

isIPV6

public boolean isIPV6()

Returns true if the value stored in this IP field is an IPV6 address. If this field has no value set, this method will return false by default.

Specified by:

isIPV6 in interface ip_field

See Also:

ip_field

isIPV6

public boolean isIPV6(short index)

Returns true if the value stored in the given element of this IP field is an IPV6 address. If no value is stored in this field, false is returned.

Specified by:

isIPV6 in interface ip_field

Parameters:

index - Array index for the value to be checked

See Also:

ip_field

verifyTypeMatch

public boolean verifyTypeMatch(java.lang.Object o)

Description copied from class: DBField

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

Specified by:

verifyTypeMatch in class DBField

verifyNewValue

public arlut.csd.ganymede.ReturnVal verifyNewValue(java.lang.Object o)

Description copied from class: DBField

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

Specified by:

verifyNewValue in class DBField

u2s

public static final byte u2s(int x)

This method maps an int value between 0 and 255 inclusive to a legal signed byte value.

s2u

public static final short s2u(byte b)

This method maps a u2s-encoded signed byte value to an int value between 0 and 255 inclusive.

isAllowedV4

private static final boolean isAllowedV4(char ch)

determines whether a given character is valid or invalid for a JIPField

Parameters:

ch - the character which is being tested for its validity

isAllowedV6

private static final boolean isAllowedV6(char ch)

determines whether a given character is valid or invalid for a JIPField

Parameters:

ch - the character which is being tested for its validity

genIPString

public static java.lang.String genIPString(java.lang.Byte[] octets)

genIPV4bytes

public static java.lang.Byte[] genIPV4bytes(java.lang.String input)

This method takes an IPv4 string in standard format and generates an array of 4 bytes that the Ganymede server can accept.

genIPV4string

public static java.lang.String genIPV4string(java.lang.Byte[] octets)

This method generates a standard string representation of an IPv4 address from an array of 4 octets.

genIPV6bytes

public static java.lang.Byte[] genIPV6bytes(java.lang.String input)

This method takes an IPv6 string in any of the standard RFC 1884 formats or a standard IPv4 string and generates an array of 16 bytes that the Ganymede server can accept as an IPv6 address.

genIPV6string

public static java.lang.String genIPV6string(java.lang.Byte[] octets)

This method takes an array of 4 or 16 bytes and generates an optimal RFC 1884 string encoding suitable for display.

main

public static void main(java.lang.String[] argv)

Test rig