norsys.netica
Class User

java.lang.Object
  |
  +--norsys.netica.User

public class User

extends java.lang.Object

A class that provides facilities for defining and retrieving arbitrary user-defined data.

Currently only Nets and Nodes possess objects of this class, but other classes may do so in future.

There is no public constructor for the User class. Access to an instance of this class is by means of the Generic.user method. For example: node.user().setString ("extraInfo", "This is some extra information.");

A User object contains accessors and mutators for the following data:

user reference		a single arbitrary object (but can be absolutely anything, including a Collection) that will NOT be saved when this Generic object is written to a file or stream, or duplicated when this Generic object is duplicated. Sample usage: node.user().setReference (myCollection); . . . Collection myCollection = (Collection) node.user().getReference();
user fields		a set of key-value pairs (attribute-value pairs), where the keys are strings and the values may be of a variety of types. These WILL be output when the Generic object is written to a file or stream. Sample usage: node.user().setString ("extraInfo", "This is some extra information."); . . . String extraInfo = node.user().getString ("extraInfo");

Since user field data is written to file when Nets are saved, issues may arise about the portability of the data that is written. If the files may someday be read by platforms other than the one creating the data, then you should try to use a compatible format. Ascii text is a good choice, since most platforms can read it.

Since:

2.20

Version:

2.21 - May 7, 2002

Method Summary

byte[]	getBytes(java.lang.String fieldName) Returns the user-defined byte array associated with this fieldName, or null, if the field was never set.
java.lang.String	getNthFieldName(int index) Returns the fieldName of the indexth user-defined named field; used for iterating through the fieldNames.
double	getNumber(java.lang.String fieldName) Returns the user-defined Number associated with this fieldName, or UNDEF_DBL, if the field was never set.
java.lang.Object	getObject(java.lang.String fieldName) Returns the user-defined Object associated with this fieldName, or null, if the field was never set.
java.lang.Object	getReference() Returns a reference to information previously attached to this object using setReference, or null if none has been attached.
java.lang.String	getString(java.lang.String fieldName) Returns the user-defined String associated with this fieldName, or null, if the field was never set.
void	removeField(java.lang.String fieldName) Remove the user field named fieldName from this object.
void	setBytes(java.lang.String fieldName, byte[] bytes) Attaches user defined byte data to this object under category 'fieldName'.
void	setNumber(java.lang.String fieldName, double fieldValue) Attaches user defined numeric data to this object under category 'fieldName'.
void	setObject(java.lang.String fieldName, java.io.Serializable fieldValue) Attaches user defined object data to this object under category 'fieldName'.
void	setReference(java.lang.Object obj) Attaches an arbitrary data object to this User object.
void	setString(java.lang.String fieldName, java.lang.String fieldValue) Attaches user defined text data to this object under category 'fieldName'.

Methods inherited from class java.lang.Object

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

Method Detail

getReference

public java.lang.Object getReference()
                              throws NeticaException

Returns a reference to information previously attached to this object using setReference, or null if none has been attached.

This information is not managed by Netica in any way. It is understood only by the program using the Netica API. It may point to whatever is desired, possibly a large structure with many fields. It is not saved to file when the net is written to file (for that see the the getUser[Bytes|Number|Object|String] suite of methods.

Version:

Versions 2.20 and later have this method. In versions previous to 2.20, this method was named Generic.getUserData.
In the C Version of the API, this function is named GetNetUserData_bn and GetNodeUserData_bn.

See Also:

setReference		Sets it
getBytes		Retrieves raw binary data that is saved to file when object is saved.
getNumber		Retrieves numeric data that is saved to file when object is saved.
getObject		Retrieves arbitrary object data that is saved to file when object is saved.
getString		Retrieves text data that is saved to file when object is saved.

Example:

    Hashtable hashTable = new Hashtable();
    hashTable.put ("Greeting", "hello");
    hashTable.put ("object1", object1);
    net.setUserReference (hashTable);
     . . .
    Hashtable hashTable2 = (Hashtable) net.getUserReference();
    String greeting = hashTable2.get ("Greeting");

setReference

public void setReference(java.lang.Object obj)
                  throws NeticaException

Attaches an arbitrary data object to this User object. The data is not saved to file when the object that owns this User object is saved.

Only your program needs to be able to understand this data. It may point to whatever is desired, possibly a large collection of other objects. This object may later be recovered using getReference.

Only one object at a time may be made the reference object.

When the owner of this User object is written to file, this reference data is not included. For user-defined field-by-field data that gets saved to file, use one of setBytes, setNumber, setObject, or setString.

Netica will not modify, free or duplicate the referenced data, even if the net or node is freed.

Parameters:

Object

obj

Any Java object

Version:

Versions 2.20 and later have this method. In versions previous to 2.20, this method was handled by Generic.setUserData.
In the C Version of the API, this function is named SetNetUserData_bn and SetNodeUserData_bn.

See Also:

getReference		Retrieves value
setBytes		Sets raw binary data that is saved to file when object is saved.
setNumber		Sets numeric data that is saved to file when object is saved.
setObject		Sets arbitrary object data that is saved to file when object is saved.
setString		Sets text data that is saved to file when object is saved.

Example:

    // Associate a java collection with a net
    //
    Hashtable hashTable = new Hashtable();
    hashTable.put ("Greeting", "hello");
    hashTable.put ("object1", object1);
    net.setUserReference (hashTable);
    net.write (stream); //-- hashTable will not be written to stream

getBytes

public byte[] getBytes(java.lang.String fieldName)
                throws NeticaException

Returns the user-defined byte array associated with this fieldName, or null, if the field was never set. For more information, see setBytes.

For fieldName pass the name of the field to be read, which was passed to setBytes when the data was set.

Parameters:

String

fieldName

The name of the field to be retrieved.

Version:

Versions 2.20 and later have this method.
In the C Version of the API, this function is named GetNetUserField_bn and GetNodeUserField_bn.

See Also:

setBytes		Sets it
getNthFieldName		Retrieve fieldNames by index. Iterate over field names
getReference		For user-managed data which is not saved when object is saved

getObject

public java.lang.Object getObject(java.lang.String fieldName)
                           throws NeticaException

Returns the user-defined Object associated with this fieldName, or null, if the field was never set. For more information, see setObject.

For fieldName pass the name of the field to be read, which was passed to setObject when the data was set.

Parameters:

String

fieldName

The name of the field to be retrieved.

Version:

Versions 2.20 and later have this method.
In the C Version of the API, this function is named GetNetUserField_bn and GetNodeUserField_bn.

See Also:

setObject		Sets it
getNthFieldName		Retrieve fieldNames by index. Iterate over field names
getReference		For user-managed data which is not saved when object is saved

getString

public java.lang.String getString(java.lang.String fieldName)
                           throws NeticaException

Returns the user-defined String associated with this fieldName, or null, if the field was never set. For more information, see setString.

For fieldName pass the name of the field to be read, which was passed to setString when the data was set.

Parameters:

String

fieldName

The name of the field to be retrieved.

Version:

Versions 2.20 and later have this method.
In the C Version of the API, this function is named GetNetUserField_bn and GetNodeUserField_bn.

See Also:

setString		Sets it
getNthFieldName		Retrieve fieldNames by index. Iterate over field names
getReference		For user-managed data which is not saved when object is saved

Example:

    /** 
     *  Returns a user field and confirms it is an ascii string.  
     *  If the string is not ascii, throw an exception.
     *  @param fieldname the userField name; must be IDname or fewer characters.
     *  @returns the userField value that is supposed to be an ascii string.
     */
    static public String getUserAsciiString (User userObj, String fieldname) throws NeticaException {
        String asciiStr = userObj.getString (fieldname);
        if ( ! Util.isAscii (asciiStr)) {
            throw new NeticaException ("Not an ascii string");
        }
        return asciiStr;
    }

getNumber

public double getNumber(java.lang.String fieldName)
                 throws NeticaException,
                        java.io.IOException

Returns the user-defined Number associated with this fieldName, or UNDEF_DBL, if the field was never set. For more information, see setNumber.

For fieldName pass the name of the field to be read, which was passed to setNumber when the data was set.

Parameters:

String

fieldName

The name of the field to be retrieved.

Version:

Versions 2.20 and later have this method.
In the C Version of the API, this function is named GetNetUserField_bn and GetNodeUserField_bn.

See Also:

setNumber		Sets it
getNthFieldName		Retrieve fieldNames by index. Iterate over field names
getReference		For user-managed data which is not saved when object is saved

setBytes

public void setBytes(java.lang.String fieldName,
                     byte[] bytes)
              throws NeticaException

Attaches user defined byte data to this object under category 'fieldName'. If fieldName was never set before, it will be defined and added to the set of defined fields for this object. If fieldName was set before, by this or any other setUser[type] method, then the old value will be overwritten with the new value. To remove a field with this fieldName entirely, call removeField.

Should this object be written to file, this data will be saved to the file with it, and will be available when this object is read back from file.

The byte[] data will be stored as a binary block.

Note, Netica Application can also read and set user fields if they are ascii strings (use the multi-purpose selector at the bottom of the node properties dialog box of version 2.00 or later).

All memory management for the internal representation of user-defined fields is managed by Netica. They are duplicated when nodes are duplicated, and freed when they are freed.

If you wish to associate user data with an owner object, but not have that data saved to file, then use setReference instead.

Parameters:

String		fieldName		The name of the field to be set.
byte[]		fieldValue		The value of the field to be set.

Version:

Versions 2.20 and later have this method.

See Also:

getBytes		Retrieves value
setNumber		Sets numeric data.
setObject		Sets arbitrary object data.
setString		Sets text data.
getNthFieldName		Retrieve fieldNames by index. Iterate over field names

setObject

public void setObject(java.lang.String fieldName,
                      java.io.Serializable fieldValue)
               throws NeticaException

Attaches user defined object data to this object under category 'fieldName'. If fieldName was never set before, it will be defined and added to the set of defined fields for this object. If fieldName was set before, by this or any other setUser[type] method, then the old value will be overwritten with the new value. To remove a field with this fieldName entirely, call removeField.

Should this object be written to file, this data will be saved to the file with it, and will be available when this object is read back from file.

The object is stored to file in Java's serialization format. This format is a binary format that is generally not understood by any other programming language. If you wish your Bayes net files to be portable across different programming platforms, or if people may directly read your Bayes net files, it is best for the data to be an ascii string. Netica Application can also read and set user fields if they are ascii strings (use the multi-purpose selector at the bottom of the node properties dialog box of version 2.00 or later). Several third party toolkits are available which will convert an arbitrary Java object to XML format (which is an ascii text format), so it can be stored using setString. Several such toolkits are listed at http://www.xml.com/pub/rg/Java_Applications.

All memory management for the internal representation of user-defined fields is managed by Netica. They are duplicated when nodes are duplicated, and freed when they are freed.

If you wish to associate user data with an owner object, but not have that data saved to file, then use setReference instead.

Parameters:

String		fieldName		The name of the field to be set.
Serializable		fieldValue		The value of the field to be set.

Version:

Versions 2.20 and later have this method.

See Also:

getObject		Retrieves value
setBytes		Sets raw binary data.
setNumber		Sets numeric data.
setString		Sets text data.
getNthFieldName		Retrieves fieldNames by index. Use to iterate over field names

setString

public void setString(java.lang.String fieldName,
                      java.lang.String fieldValue)
               throws NeticaException

Attaches user defined text data to this object under category 'fieldName'. If fieldName was never set before, it will be defined and added to the set of defined fields for this object. If fieldName was set before, by this or any other setUser[type] method, then the old value will be overwritten with the new value. To remove a field with this fieldName entirely, call removeField.

Should this object be written to file, this data will be saved to the file with it, and will be available when this object is read back from file.

The text data may be arbitrary Unicode, but if you wish people, Netica Application, or other programs to be able to interpret the user field data in the net files you create, then it is best for the data to contain only ascii characters. Netica Application can examine and set user fields if they are ascii strings (use the multi-purpose selector at the bottom of the node properties dialog box of version 2.00 or later). A helpful method to ensure your text is ascii is setUserAsciiString() which is provided in the example below.

The text is stored internally to file in "UTF-8" format.

All memory management for the internal representation of user-defined fields is managed by Netica. They are duplicated when nodes are duplicated, and freed when they are freed.

If you wish to associate user data with an owner object, but not have that data saved to file, then use setReference instead.

Parameters:

String		fieldName		The name of the field to be set.
String		fieldValue		The value of the field to be set.

Version:

Versions 2.20 and later have this method.

See Also:

Util.isAscii		Tests whether a string contains only Ascii characters.
getString		Retrieves value.
setBytes		Sets raw binary data.
setNumber		Sets numeric data.
setObject		Sets arbitrary object data.
getNthFieldName		Retrieve fieldNames by index. Iterate over field names

Example:

    /** 
     *  Set a user field to an ascii string.  
     *  If the string is not ascii, throw an exception.
     *  Useful to guarantee platform independence of Bayes nets written to 
     *  file (not all platforms can deal with UTF-8 strings, but most will 
     *  read ascii).
     *  @param userObj   the User object whose field we wish to set.
     *  @param fieldname the userField name; must be IDname or fewer characters.
     *  @param asciiStr  the userField value that is supposed to be an ascii string.
     */
    static public void setUserAsciiString (User userObj, String fieldname, String asciiStr) throws NeticaException {
        if (!Util.isAscii (asciiStr)) {
            throw new NeticaException ("Not an ascii string");
        }
        userObj.setString (fieldname, asciiStr);
    }

setNumber

public void setNumber(java.lang.String fieldName,
                      double fieldValue)
               throws NeticaException,
                      java.io.IOException

Attaches user defined numeric data to this object under category 'fieldName'. If fieldName was never set before, it will be defined and added to the set of defined fields for this object. If fieldName was set before, by this or any other setUser[type] method, then the old value will be overwritten with the new value. To remove a field with this fieldName entirely, call removeField.

Should this object be written to file, this data will be saved to the file with it, and will be available when this object is read back from file.

The numeric field, when stored to file, will be stored as an ascii string. If you wish your Bayes net files to be portable across different operating systems, or if people or other programs may directly read your Bayes net files, it is best for the data to be an ascii string. Netica Application can also read and set user fields if they are ascii strings (use the multi-purpose selector at the bottom of the node properties dialog box of version 2.00 or later).

If you wish to associate numeric data with an owner object, but not have that data saved to file, then use setReference instead.

Parameters:

String		fieldName		The name of the field to be set.
double		fieldValue		The value of the field to be set.

Version:

Versions 2.20 and later have this method.

See Also:

getNumber		Retrieves value
setBytes		Sets raw binary data.
setObject		Sets arbitrary object data.
setString		Sets text data.
getNthFieldName		Retrieve fieldNames by index. Iterate over field names

removeField

public void removeField(java.lang.String fieldName)
                 throws NeticaException

Remove the user field named fieldName from this object.

Parameters:

String

fieldName

The name of the field to be retrieved.

Version:

Versions 2.20 and later have this method.
In the C Version of the API, this function is named SetNetUserField_bn and SetNodeUserField_bn.

getNthFieldName

public java.lang.String getNthFieldName(int index)
                                 throws NeticaException

Returns the fieldName of the indexth user-defined named field; used for iterating through the fieldNames.

Pass any non-negative integer for index. If it is larger than the largest index, then null will be returned.

This method is meant to iterate through the various fields. Don't assume that their ordering will remain the same after a call to any method that sets a user field ( setBytes, setNumber, setObject, or setString).

Parameters:

int

index

The index into the User Field list.

Version:

Versions 2.20 and later have this method.
In the C Version of the API, this function is named GetNetNthUserField_bn and GetNodeNthUserField_bn.

See Also:

getBytes		Retrieves raw binary data
getNumber		Retrieves numeric data
getObject		Retrieves arbitrary object data
getString		Retrieves text data
setBytes		Sets raw binary data
setNumber		Sets numeric data
setObject		Sets arbitrary object data
setString		Sets text data