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 Generic

java.lang.Object
  |
  +--norsys.netica.Generic
All Implemented Interfaces:
NeticaListener
Direct Known Subclasses:
Net, Node, State
public abstract class Generic
extends java.lang.Object
implements NeticaListener

A class that provides generic useful documentation and utility information regarding a Netica object.

Currently only Net, Node, and State extend this class, but other classes may do so in future.

There is no public constructor for the Generic class; obtain a Generic object by constructing a Node or Net or by calling Node.state

A Generic object contains accessors and mutators for the following data:
name    A size-restricted and character restricted name for the object. Must contain only ascii letters, digits, 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.
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 saved when the Generic object is written to a file or stream. All userFields are placed in the User object owned by this Generic. Access them by calling user. For example:   node.user().setString ("extraInfo", "This is some extra information.");
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. The userReference resides in the User object owned by this Generic. Access it by calling user. For example:   node.user().setReference (myCollection);

Note. Currently States only have name and title methods. This restriction will be removed in a future release of Netica.

Since:
2.12
Version:
2.20 - May 7, 2002

Field Summary
static int NAME_MAX

The maximum number of characters in the name of a Generic Netica object (e.g., Node, Net, State).
 
Method Summary
 void addListener(NeticaListener listener)

Adds the given listener to this object's list of listeners.
 void eventOccurred(NeticaEvent event)

Netica calls back this method when an event occurred to an object we expressed interest in(by calling addListener.
 java.lang.String getComment()

Gets the documentation text concerning this object.
 Environ getEnviron()

Returns the Environ this object belong's to.
 java.lang.String getName()

Returns the identifer name of this object.
 void getNthUserField(int index, java.lang.String[] name, java.lang.Object[] value)

Deprecated. Works only with objects stored via user().setObject(). This method will be phased out.
 java.lang.String getTitle()

Gets the unrestricted label of this object.
 java.lang.Object getUserData()

Deprecated. This method is now available as User.getReference.

 java.lang.Object getUserField(java.lang.String fieldName)

Deprecated. This method has been replaced by the suite of User methods User.getBytes, User.getNumber, User.getObject, and User.getString.
 void removeListener(NeticaListener listener)

Removes the given listener from this object's list of listeners.
 void setComment(java.lang.String comment)

Sets the documentation or a description of an object.
 void setName(java.lang.String name)

Changes the name of this object to be name.
 void setTitle(java.lang.String title)

Sets the title of this object to the unrestricted string title.
 void setUserData(java.lang.Object obj)

Deprecated. This method is now available as User.setReference.

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

Deprecated. This method has been replaced by the suite of User methods User.setBytes, User.setNumber, User.setObject, and User.setString.
 java.lang.String toString()

Returns the value of getName.
 User user()

Retrieve the User object that stores user controlled data associated with this object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NAME_MAX

public static final int NAME_MAX
The maximum number of characters in the name of a Generic Netica object (e.g., Node, Net, State). Currently it is 30, and not likely to change.

Method Detail

getEnviron

public Environ getEnviron()
                   throws NeticaException
Returns the Environ this object belong's to.

Version:
This method is available in all versions (JAVA API only).

getName

public java.lang.String getName()
                         throws NeticaException
Returns the identifer name of this 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 always have distinct names, and two different node-states in the same node always 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 State's name, this will return a default name of the form "s#" where '#' is the state index.

Version:

This method 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 this 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.

For Generic State objects only



Parameters:
String    name    The new name desired.

Version:
This method is available in all versions.
In the C Version of the API, this function is called SetNetName_bn, SetNodeName_bn, or SetNodeStateName_bn.
See Also:
getName    Retrieves value
setTitle    Doesn't have the restriction of an IDname

getTitle

public java.lang.String getTitle()
                          throws NeticaException
Gets the unrestricted label of this object.

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

This may be different from this object's "name".

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

Keep in mind that titles are not necessarily unique.

Version:

This method 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 this object's name (limited chars and length, always exists)

setTitle

public void setTitle(java.lang.String title)
              throws NeticaException
Sets the title of this 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.

Titles never have to be unique; two nodes in the same net can have the same title as can two states in the same node, although usually that is not advisable.

Parameters:
String    title    The new title desired.

Version:

This method 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

getComment

public java.lang.String getComment()
                            throws NeticaException
Gets the documentation text concerning this object. Returns the comment associated with this object, or the empty string (rather than null) if this 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 State's do not have comment fields, and so an exception is thrown if you attempt to call this method on a State object.

Version:

This method 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
Sets the documentation or a description of an object.

This associates the character string comment with this 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 this object, its purpose or applicability, background information on the problem domain, a copyright notice, how to use this 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, and this object is a Net or Node, use its User object (see user).

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

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

Parameters:
String    comment    A text String of arbitrary length.

Version:

This method 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
user    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.setComment( net.getComment() + addon);

user

public User user()
          throws NeticaException
Retrieve the User object that stores user controlled data associated with this object.

Currently, only Net and Node objects have User objects.

Version:

Versions 2.20 and later have this method.

getUserData

public java.lang.Object getUserData()
                             throws NeticaException
Deprecated. This method is now available as User.getReference.

setUserData

public void setUserData(java.lang.Object obj)
                 throws NeticaException
Deprecated. This method is now available as User.setReference.

getUserField

public java.lang.Object getUserField(java.lang.String fieldName)
                              throws NeticaException
Deprecated. This method has been replaced by the suite of User methods User.getBytes, User.getNumber, User.getObject, and User.getString.

This method has been replaced with a suite of getUser[format] methods: GetGenericUserBytes, GetGenericUserNumber, GetGenericUserObject, and GetGenericUserString which allow you to control the format in which field values are stored to file. Use them instead, as this method will be phased out.

Parameters:
String    fieldName    The name of the field to be retrieved.

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

setUserField

public void setUserField(java.lang.String fieldName,
                         java.io.Serializable fieldValue)
                  throws NeticaException
Deprecated. This method has been replaced by the suite of User methods User.setBytes, User.setNumber, User.setObject, and User.setString.

This method has been replaced with a suite of user().setUser[format] methods: setBytes, SetGenericUserNumber, SetGenericUserObject, SetGenericUserString which allow you to control the format in which field values are stored to file. Use them instead, as this method will be phased out.

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

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

getNthUserField

public void getNthUserField(int index,
                            java.lang.String[] name,
                            java.lang.Object[] value)
                     throws NeticaException
Deprecated. Works only with objects stored via user().setObject(). This method will be phased out.

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

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 method is meant to iterate through the various fields. Don't assume that their ordering will remain the same after a call to setUserField on this object.

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

Parameters:
int    index    The index into the User Field list.
String[]    name    A one element array for recovering the name of the nth user field.
Object[]    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

Version:

Versions 2.07 and later have this method.
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

eventOccurred

public void eventOccurred(NeticaEvent event)
Netica calls back this method when an event occurred to an object we expressed interest in(by calling addListener. Meets the requirement of the NeticaListener interface.

If you override this method, be sure to call the base class method (super.eventOccurred();).

Parameters:
NeticaEvent    event    An object providing information about the event that occurred.

Version:

This method is available in all versions.
See Also:
addListener    Indicates an object wants to receive events

Example: 
See  addListener
Specified by:
eventOccurred in interface NeticaListener

addListener

public void addListener(NeticaListener listener)
                 throws NeticaException
Adds the given listener to this object's list of listeners. If any significant event occurs to this object(e.g., REMOVE_EVENT), Netica will inform each such listener.

Parameters:
NeticaListener    listener    The object to be informed.

Version:
This method is available in all versions.
In the C Version of the API, this function is called AddNetListener_bn and AddNodeListener_bn.
See Also:
removeListener    Removes a listener from the listener list
eventOccurred    Receives the event

Example: 
The following complete program illustrates how any java object, if it chooses to implement the NeticaListener interface, can listen to NeticaEvents:

   /* 
    * SampleListener.java
    *
    * Example use of NeticaListener interface to listen to NeticaEvents on objects.
    *
    * Copyright (c) 2002 by Norsys Software Corp.
    */
   
   import norsys.netica.*;
   
   public class SampleListener implements NeticaListener {
   
       public static void main (String[] arg) {
           SampleListener sa = new SampleListener();
           sa.run();
       }
   
       public void run() {
           try {
               Environ env = new Environ (null);
               Net net = new Net();
               net.setName("testNet");
               Node node1 = new Node ("node1", 0, net);
               Node node2 = new Node ("node2", 0, net);
               Node node3 = new Node ("node3", 0, net);
               Node node4 = new Node ("node4", 0, net);
   
               node1.addListener (this);
               node2.addListener (this);
               node3.addListener (this);
               // note, we aren't listening to node4
               net.addListener (this);
   	    
               System.out.println("----------- A");
               node2.delete();
               System.out.println("----------- B");
               net.delete();
               System.out.println("----------- C");
       }
   	 catch (Exception e) {
   	     e.printStackTrace();
   	 }
   }
   
       public void eventOccurred(NeticaEvent ne) {
           if (ne.getKind() == NeticaEvent.REMOVE_EVENT) {
               System.out.print ("The following object has been removed from Netica: ");
               Object obj = ne.getObject(); // the object generating the event
               if (obj instanceof Node) {
                   System.out.print ("(Node): ");
               }
               else if (obj instanceof Net) {
                   System.out.print (" (Net): ");
               }
               System.out.println (obj);
           }
       }
   }
   
   
When run, the above program prints the following:

   
   ----------- A
   The following object has been removed from Netica: (Node): node2
   ----------- B
   The following object has been removed from Netica: (Node): node1
   The following object has been removed from Netica: (Node): node3
   The following object has been removed from Netica:  (Net): testNet
   ----------- C

removeListener

public void removeListener(NeticaListener listener)
                    throws NeticaException
Removes the given listener from this object's list of listeners. If the object supplied is not a current listener, an exception will be thrown.

Parameters:
NeticaListener    listener    The object to be removed from the listener list.

Version:
This method is available in all versions.
In the C Version of the API, this function is called AddNetListener_bn and AddNodeListener_bn.
See Also:
addListener    Adds a listener to the listener list

toString

public java.lang.String toString()
Returns the value of getName.

Version:
This method is available in all versions.
Overrides:
toString in class java.lang.Object
Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD