| NORSYS SOFTWARE © 2011 | NETICA API | JAVA VERSION 5.02

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `General.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 General object is written to a file or stream, or duplicated when this General 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 General 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:
  5.02 - April 8, 2011

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

public byte[ ] getBytes ( |
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

public double getNumber ( |
String | fieldName
| ) throws NeticaException, 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

public 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

public Object getObject ( |
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

public 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 General.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");

public String getString ( |
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 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;
        }

public void removeField ( |
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.

public void setBytes ( |
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

public void setNumber ( |
String | fieldName,
double | fieldValue
| ) throws NeticaException, 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, callremoveField.

  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

public void setObject ( |
String | fieldName,
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.
  java.io.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

public void setReference ( |
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.

  Likewise, when objects are duplicated (e.g., `Net.copyNodes` and Net(Net,String,Environ,String)), this reference data is not included.

  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 General.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

public void setString ( |
String | fieldName,
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 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);
        }

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD