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