norsys.netica
Class Doc

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

public class Doc

extends java.lang.Object

A collection of descriptive information regarding a Netica net, node, or node-state. The particular object is called the "documentation owner" or "owner-object".

Currently only nets, nodes, and node-states may possess Doc objects.

There is no public constructor for the Doc class. You can access an owner-object's Doc object only by calling Net.doc(), Node.doc(), or Node.docState(). Examples:

net.doc().setTitle("MyNet");
String name = node.doc().getName();
node.docState(0).setName( "present" );
node.docState(1).setName( "absent" );
node.docState("present").setTitle( "PSA level greater than 20 ng/mL" );

A Doc object contains accessors and mutators for the following data concerning its parent object:

name		a size-restricted and character restricted name for the object. Must be Ascii, contain only letters, numbers, or underscores, start with a letter, and be of 30 characters or less in length.
title		an unrestricted name for the object. May be any length of arbitrary Unicode, but recommended that it not be very long (the comment field is available for that).
comment		an unrestricted comment text block (any length of arbitrary Unicode), but semantically meant to describe or give detailed documentation concerning the object in question.
userData		a single arbitrary object (but can be absolutely anything, including a Collection) that will NOT be saved when the owner-object is written to a file or stream, or duplicated when the object is duplicated.
userFields		a set of key-value pairs (attribute-value pairs), where the keys are strings and the values may be arbitrary objects, but must be serializable. These WILL be output when the owner-object is written to a file or stream.

Note. Currently node-states only have name and title documentation. This restriction will be removed in a future release of Netica.

Since:

2.12

Method Summary

java.lang.String	getComment() Get documentation text concerning an owner-object.
java.lang.String	getName() Returns the identifer name of the owner-object.
void	getNthUserField(int index, java.lang.String[] name, java.lang.Object[] value) Reads the user-defined named field (i.e., attribute-value) data associated with the owner-object, by index rather than field name; used for iterating through the pairs.
java.lang.String	getTitle() Gets the unrestricted label of an owner-object.
java.lang.Object	getUserData() Returns a reference to information previously attached to this owner-object using setUserData, or null if none has been attached.
java.lang.Object	getUserField(java.lang.String fieldName) Reads the user-defined data associated with the owner-object on a named-field basis (i.e., attribute-value).
void	setComment(java.lang.String comment) Set documentation or a description of an owner-object.
void	setName(java.lang.String name) Changes the name of the owner-object to be name.
void	setTitle(java.lang.String title) Sets the title of the owner-object to the unrestricted string title.
void	setUserData(java.lang.Object obj) Attaches an arbitrary data object to an owner-object.
void	setUserField(java.lang.String fieldName, java.io.Serializable fieldValue) Attaches user defined data to this owner-object under category 'fieldName'.

Methods inherited from class java.lang.Object

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

Method Detail

getName

public java.lang.String getName()
                         throws NeticaException

Returns the identifer name of the owner-object.

You can count on the name to be present, and to be a legal IDname , which means that it begins with a letter, is composed only of ascii letters, numbers, or underscores, and is NAME_MAX or fewer characters in length.

Note that two different nets in Netica's memory may have the same name, however, two different nodes in a net must have distinct names, and two different node-states in a node must have distinct names also.

If you have never set a net's name, it will be assigned a default name of the form "unnamed_#" where '#' is an integer.

If you have never set a node-state's name, this will return a default name of the form "s#" where '#' is the state index.

Version:

This function is available in all versions.
In the C Version of the API, this function is called GetNetName_bn, GetNodeName_bn, and GetNodeStateName_bn.

See Also:

setName		Sets it
getTitle		Longer, unrestricted label

setName

public void setName(java.lang.String name)
             throws NeticaException

Changes the name of the owner-object to be name.

name must be a legal IDname, which means it must have NAME_MAX or fewer ascii characters, all of which are letters, digits or underscores, and it must start with a letter.

Two nodes in the same net may not have identical names, and two states in the same node may not have identical names (case sensitive comparison).

Throws a NeticaException, if the name is invalid, explaining why it is invalid.

Special considerations for state names
- The default (initial) name for each state is "s#", where # is its stateIndex.
- If you pass null (not the empty string) for name, it will reset all the state names for the node to their defaults ("s0" ... "sK", where K = node.numStates() - 1).
- Discretized continuous nodes may have their states named, as well as regular discrete nodes. If you call this method on continuous nodes that have not been discretized, an exception will be thrown.
- It may be more convenient to set the names of all the states at the same time; for that, see setStateNames.

Version:

This function is available in all versions.
In the C Version of the API, this function is called SetNetName_bn, SetNodeName_bn, and SetNodeStateName_bn.

See Also:

getName		Retrieves value
setTitle		Doesn't have the restriction of an IDname

Parameters:

name - The new name desired.

getTitle

public java.lang.String getTitle()
                          throws NeticaException

Gets the unrestricted label of an owner-object.

Returns the title of the owner-object, or the empty string (rather than null) if the owner-object does not have a title.

This may be different from the owner-object's "name".

There is no restriction on the length of the title, or on what characters it might contain.

Version:

This function is available in all versions.
In the C Version of the API, this function is called GetNetTitle_bn, GetNodeTitle_bn, and GetNodeStateTitle_bn.

See Also:

setTitle		Sets it
getName		Gets the owner-object's name (limited chars and length, always exists)

setTitle

public void setTitle(java.lang.String title)
              throws NeticaException

Sets the title of the owner-object to the unrestricted string title. There are no restrictions on its length or what characters it may contain (unlike the "name").

It is advised not to put too much information in the title, since the "comment" field is available for that.

To remove a title, pass null or the empty string for title.

Version:

This function is available in all versions.
In the C Version of the API, this function is called SetNetTitle_bn, SetNodeTitle_bn, and SetNodeStateTitle_bn.

See Also:

getTitle		Retrieves value
setName		The short, restricted name
setComment		For longer descriptions

Parameters:

title - The new title desired.

getComment

public java.lang.String getComment()
                            throws NeticaException

Get documentation text concerning an owner-object. Returns the comment associated with the owner-object, or the empty string (rather than null) if the owner-object does not have a comment.

The comment may contain anything, but see setComment for what it's meant to contain.

There is no restriction on the length of the comment, or on what characters it might contain.

Note. Currently node-state's do not have comment fields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

This function is available in all versions.
In the C Version of the API, this function is called GetNetComment_bn and GetNodeComment_bn.

See Also:

setComment

Sets it

setComment

public void setComment(java.lang.String comment)
                throws NeticaException

Set documentation or a description of an owner-object.

This associates the character string comment with the owner-object (net or node) to help document it.

The comment may contain anything, but is usually used to store such things as the origin of the owner-object, its purpose or applicability, background information on the problem domain, a copyright notice, how to use the owner-object, notes for future changes, etc. It is best if the comment consists only of that sort of descriptive information (and as ascii text characters), in order to meet expectations in case you share this Bayes net with other people or view it with Netica Application. If you wish to attach other data, use setUserField.

To remove a comment, pass null or the empty string for comment.

Note. Currently node-state's do not have comment fields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

This function is available in all versions.
In the C Version of the API, this function is called SetNetComment_bn and SetNodeComment_bn.

See Also:

getComment		Retrieves value
setUserField		To attach other types of information, and have it saved to file with the net

Example:

  // append String addon to the end of the existing comment for net
  //
  net.doc().setComment( net.doc().getComment() + addon );

Parameters:

comment - a text String of arbitrary length.

getUserData

public java.lang.Object getUserData()
                             throws NeticaException

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

This information 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 getUserField).

Note. Currently node-state's do not have userData fields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

This function is available in all versions.
In the C Version of the API, this function is called GetNetUserData_bn and GetNodeUserData_bn.

See Also:

setUserData		Sets it
getUserField		Named field (attribute-value) data, which gets saved upon being output

setUserData

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

Attaches an arbitrary data object to an owner-object.

Attaches to an owner-object the data referenced by data. 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 getUserData.

Only one user object may be attached to an owner-object at a time. When an owner-object is written to file, this user data is not included. For user-defined field-by-field data that gets saved to file, see setUserField.

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

Note. Currently node-state's do not have userData fields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

This function is available in all versions.
In the C Version of the API, this function is called SetNetUserData_bn and SetNodeUserData_bn.

See Also:

getUserData		Retrieves value
setUserField		Attach information field-by-field, and have it saved upon being output

Example:

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

Parameters:

obj - Any Java object

getUserField

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

Reads the user-defined data associated with the owner-object on a named-field basis (i.e., attribute-value). For more information, see setUserField.

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

This function will return a reference to the data, or null, if the field was never set.

Some helpful methods to read user fields which are numbers and strings are supplied in the examples below. These methods are defined in NetEx.java and NodeEx.java. See setUserField for the matching methods that do the setting.

Note. Currently node-state's do not have userFields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

Versions 2.00 and later have this function.
In the C Version of the API, this function is called GetNetUserField_bn and GetNodeUserField_bn.

See Also:

setUserField		Sets it
getNthUserField		Retrieve field by index. Iterate over fields
getUserData		For user-managed data which is not saved upon being output

Example #1:

The following method is available in NodeEx.java and NetEx.java:
  /** 
   *  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.
   */
  public String getUserAsciiString (String fieldname ) throws NeticaException {
      String asciiStr = (String) doc().getUserField (fieldname);
      if ( ! Util.isAscii (asciiStr)) {
          throw new NeticaException (20000, "Not an ascii string");
      }
      return asciiStr;
  }

Example #2:

The following method is available in NodeEx.java and NetEx.java:
  /** 
   *  Retrieves a number that was written to a user field with setUserNumber().
   *  @param fieldname the userField name; must be IDname or fewer characters.
   *  @returns the userField value that is supposed to be a number.
   */
  public double getUserNumber (String fieldname) throws Exception {
      String value = (String) doc().getUserField (fieldname);
      return Double.parseDouble (value);
  }

Parameters:

fieldName - The name of the field to be retrieved.

setUserField

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

Attaches user defined data to this owner-object under category 'fieldName'. If fieldName was never set before, it will be defined and added to the set of defined fields for this owner-object. If fieldName was set before, the old value will be overwritten with the new value. To remove a field entirely, call this function passing null for fieldValue.

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

The data may be of any type, but 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). Some helpful functions to set user fields to numbers and strings are setUserNumber() and setUserAsciiString(), which are provided in both NetEx.java and NodeEx.java, and in the examples below. See getUserField for the matching functions that do retrieval.

All memory management for the internal representation of user-defined fields is managed by Netica. It is 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 setUserData instead.

Note. Currently node-state's do not have userFields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

Versions 2.00 and later have this function.
In the C Version of the API, this function is called SetNetUserField_bn and SetNodeUserField_bn.

See Also:

getUserField		Retrieves value, by its name
getNthUserField		Iterate through the user fields of this object
setUserData		To attach completely user-managed data (not saved to file)

Example #1:

The following method is available in NodeEx.java and NetEx.java:
  /** 
   *  Set a user field to an ascii string.  
   *  If the string is not ascii, throw an exception.
   *  You can use getUserAsciiString() to retrieve the stored value.
   *  This method is useful to guarantee platform independence of Bayes nets written to file,
   *  since not all software platforms can deal with standard unicode strings, but most will read ascii.
   *  @param fieldname the userField name; must be IDname or fewer characters. //mroman do reverse
   *  @param asciiStr  the userField value that is supposed to be an ascii string.
   */
  public void setUserAsciiString (String fieldname, String asciiStr ) throws NeticaException {
      if ( ! Util.isAscii( asciiStr ) ) {
          throw new NeticaException( 20000, "Not an ascii string" );
      }
      doc().setUserField (fieldname, asciiStr);
  }

Example #2:

The following method is available in NodeEx.java and NetEx.java:
  /** 
   *  Set a user field to a number.
   *  This method is useful to guarantee both the readability and platform independence of Bayes
   *  nets written to file, since the number will be written to the file as an ascii string.
   *  You can use getUserNumber() to conveniently retrieve the stored value.
   *  @param fieldname the userField name; must be IDname or fewer characters.
   *  @param num       a double whose String representation will be set to the userField's value.
   */
  public void setUserNumber (String fieldname, double num) throws NeticaException {
      doc().setUserField (fieldname, "" + num);
  }

Parameters:

fieldName - The name of the field to be set.

fieldValue - The value of the field to be set.

getNthUserField

public void getNthUserField(int index,
                            java.lang.String[] name,
                            java.lang.Object[] value)
                     throws NeticaException

Reads the user-defined named field (i.e., attribute-value) data associated with the owner-object, by index rather than field name; used for iterating through the pairs. For more information on user fields, see setUserField.

Pass any non-negative integer for index. If it is larger than the last field, name[0] will be set to the empty string ("").

name[0] will be set to the name of the field which was passed to setUserField when the data was set, and value[0] will be set to the data.

If value is null, it won't be set.

This function is meant to iterate through the various fields. Don't assume that their ordering will remain the same after a call to setUserField on the owner-object.

Note. Currently node-state's do not have userFields, and so an exception is thrown if you attempt to call this method on a node-state.

Version:

Versions 2.07 and later have this function.
In the C Version of the API, this function is called GetNetNthUserField_bn and GetNodeNthUserField_bn.

See Also:

setUserField		Sets them
getUserField		Retrieve field by name

Parameters:

index - The index into the User Field list.

name - A one element array for recovering the name of the nth user field.

value - A one element array for recovering the value of the nth user field. You may leave this null, if you just want the field names recovered