norsys.netica
Class Environ

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

public class Environ
extends java.lang.Object

The background environment for all Netica operations.

Since:
All versions
Version:
5.04 - January 21, 2012

Field Summary
static int COMPLETE_CHECK

The most thorough argument checking level; use only for debugging.

static double INFINITY

The number used to represent an infinite numeric value; the negative of this number represents negative infinity.

static int NO_CHECK

Turns off all argument checking.

static int QUICK_CHECK

Only does argument checking that can be done very quickly.

static int REGULAR_CHECK

Does argument checking suitable for software development, and final releases of your software where speed is not significant.

static double UNDEF_DBL

The number used to represent unknown or nonexistent numeric values.

 
Constructor Summary
Environ(java.lang.String license)

Constructs an initialized Netica environment.

 
Method Summary
 java.lang.String controlConcurrency(java.lang.String command, java.lang.String value)

This function is used to control how Netica operates in multi-threaded environments.

 void finalize()

Closes down Netica and frees all its resources (e.g., memory).

 int getArgumentChecking()

Returns the current argument checking level, which is the degree to which Netica checks method call arguments.

 char getCaseFileDelimChar()

Gets the character to use as a delimeter when creating case files.

static Environ getDefaultEnviron()

Returns the last created Environ.

 double getMaxMemoryUsage()

Deprecated. use getMemoryUsageLimit() instead.

 double getMemoryUsageLimit()

Returns the current limit on memory that Netica is permitted to allocate for tables.

 char getMissingDataChar()

Gets the character used to indicate missing data when creating case files.

 java.lang.Class getNetClass()

 

 java.lang.Class getNodeClass()

 

 int getVersion()

Returns the version number of Netica, multiplied by 100.

 java.lang.String getVersionString()

Returns a String consisting of the full version number, a space, a code for the type of machine or OS it is running on, a comma, the name of the program, and finally a code indicating some build information (in parentheses).

 void setArgumentChecking(int setting)

Sets the level to which Netica checks all arguments you pass it (one of NO_CHECK, QUICK_CHECK, REGULAR_CHECK, COMPLETE_CHECK).

 void setCaseFileDelimChar(char newChar)

Sets the symbol used to separate data fields in a case file being created by Netica.

 void setMaxMemoryUsage(double maxMem)

Deprecated. use setMemoryUsageLimit (maxMem) instead.

 void setMemoryUsageLimit(double maxMem)

Call this method anytime to adjust the amount of memory that Netica is permitted to allocate for tables.

 void setMissingDataChar(char newChar)

Sets the symbol to be used for indicating missing data fields in a case file created by Netica.

 void setNetClass(java.lang.Class netClass)

 

 void setNodeClass(java.lang.Class nodeClass)

 

 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

public static final  int COMPLETE_CHECK 
The most thorough argument checking level; use only for debugging. May be very slow. See setArgumentChecking.


public static final  int NO_CHECK 
Turns off all argument checking. Final release versions of your software should normally use QUICK_CHECK instead. See setArgumentChecking.


public static final  int QUICK_CHECK 
Only does argument checking that can be done very quickly. Suitable for final release versions of your software. See setArgumentChecking.


public static final  int REGULAR_CHECK 
Does argument checking suitable for software development, and final releases of your software where speed is not significant. See setArgumentChecking.


public static double INFINITY 
The number used to represent an infinite numeric value; the negative of this number represents negative infinity.


public static double UNDEF_DBL 
The number used to represent unknown or nonexistent numeric values.

Constructor Detail
public Environ (
 String  license 
) throws NeticaException
Constructs an initialized Netica environment.

For license pass the license string provided to you when you purchased Netica, or null if you don't have one. The behavior of the Netica system may be limited by the license you use.

The Environ constructed becomes the "default" environment. The Net and Streamer classes have convenience constructors that assume the default environment.

Currently it is possible to have only one global environment (which can be accessed by calling the static method getDefaultEnviron).

Parameters:
String    license    The license string provided to you when you purchased Netica, or null if you don't have one.

Version:

This method is available in all versions.
In the C Version of the API, this function is named NewNeticaEnviron_ns and InitNetica2_bn (combined).
Example:
 // The following is a complete Netica application.
 // Note that you do not need to explicitly close down a Netica environment; the garbage
 // collector or the operating system upon exit will free all Netica resources.
 public static void main (String[] args) {
     Environ env = new Environ (null);
     System.out.println ("Version of Netica-J running: " + env.getVersionString());
 }
Method Detail
public String controlConcurrency (
 String  command
 String  value 
) throws NeticaException
This function is used to control how Netica operates in multi-threaded environments.

You can call it repeatedly with different values of command and value to make several settings.

If command is the string "ExternalThreads", then value may be one of:
Serialize    All calls to Netica functions are serialized by blocking at the entrance to API functions, and waiting until all other Netica API functions are completed before proceeding. This will result in correct behaviour under all multi-threading environments, but may result in delays for some of your threads if other of your threads are requesting time-consuming operations.
OptimizeSafely    Netica will do thread synchronization/waiting so that only one thread can operate on a Bayes net at a time, but different threads can operate on different Bayes nets independently, without any waiting.
CallerGuaranteesSafety    Netica does not do any thread synchronization or waiting, which means that you must manage that (which can result in failure if not done right). Only use this in a single-threaded environment (or only one thread with access to Netica), or with consultation from Norsys.
    
The default value for ExternalThreads is OptimizeSafely. In versions previous to 5.02 the default was Serialize.

Other commands/values will soon be available.

Parameters:
String    command    The concurrency control parameter whose value is to be set.
String    value    The value of the supplied command.

Version:

Versions 5.02 and greater have this method.
In the C Version of the API, this function is named ControlConcurrency_ns.
See Also:
RandomGenerator    In multi-thread environments, can be used to make software deterministic, by having a separate random generator for each thread
setMemoryUsageLimit    May want to allocate more memory in a multi-threaded environment


public void finalize ( ) throws NeticaException
Closes down Netica and frees all its resources (e.g., memory).

No data structure that was returned by any Netica API method will have valid contents after calling finalize.

Netica may be stopped (with finalize) and then later restarted (with new Environ), but no data structures created by one session may be used by another.

In a multi-threaded environment, ensure that only one thread calls finalize, and after that, no threads may use any Netica method.

Generally, you need never be concerned about JAVA's virtual machine automatically garbage collecting your Environ, should it go out of scope, since all Net's and Node's maintain an internal reference to their Environ.

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

Version:

This method is available in all versions.
In the C Version of the API, this function is named CloseNetica_bn.
See Also:
Environ    Creates the Environ

Overrides:
finalize in class java.lang.Object

public int getArgumentChecking ( ) throws NeticaException
Returns the current argument checking level, which is the degree to which Netica checks method call arguments.

The value returned will be one of NO_CHECK, QUICK_CHECK, REGULAR_CHECK, or COMPLETE_CHECK. For more information, see setArgumentChecking.

Version:

This method is available in all versions.
In the C Version of the API, this function is named ArgumentChecking_ns.
See Also:
setArgumentChecking    Sets it


public char getCaseFileDelimChar ( ) throws NeticaException
Gets the character to use as a delimeter when creating case files. For more information, see setCaseFileDelimChar.

Version:
This method is available in all versions.
In the C Version of the API, this function is named SetCaseFileDelimChar_ns.
See Also:
setCaseFileDelimChar    Sets value

Example:

public static Environ getDefaultEnviron ( )
Returns the last created Environ. The last created Environ is known as the "default Environ". It is used by several constructors, as a convenience.

If an Environ has yet to be constructed, then null will be returned.

Use Environ to construct a new Environ.

Version:

This method is available in all versions.
See Also:
Streamer(String)    Constructs a Streamer in the default Environ
Net()    Constructs a Net in the default Environ
Environ    Constructs an Environ, making it the default one


public double getMemoryUsageLimit ( ) throws NeticaException
Returns the current limit on memory that Netica is permitted to allocate for tables. See setMemoryUsageLimit for further documentation.

Version:
Versions 2.15 and later have this method.
In versions previous to 2.26, this method was named getMaxMemoryUsage.
In the C Version of the API, this function is named LimitMemoryUsage_ns.
See Also:
setMemoryUsageLimit    Sets it


public char getMissingDataChar ( ) throws NeticaException
Gets the character used to indicate missing data when creating case files. For more information, see setMissingDataChar.

Version:
This method is available in all versions.
In the C Version of the API, this function is named SetMissingDataChar_ns.
See Also:
setMissingDataChar    Sets it


public Class getNetClass ( )

public Class getNodeClass ( )

public int getVersion ( ) throws NeticaException
Returns the version number of Netica, multiplied by 100. For example, if the version of Netica currently running is 1.21, then 121 is returned.

Version:
This method is available in all versions.
In the C Version of the API, this function is named GetNeticaVersion_bn.
Example:
  int ver = Environ.getDefaultEnviron().getVersion();
  System.out.println ("The version number of Netica-J is " + (ver / 100.0));

public String getVersionString ( ) throws NeticaException
Returns a String consisting of the full version number, a space, a code for the type of machine or OS it is running on, a comma, the name of the program, and finally a code indicating some build information (in parentheses). An example is:    2.06 Win, Netica-J (AB).

Version:
This method is available in all versions.
In the C Version of the API, this function is named GetNeticaVersion_bn.
Example:
  System.out.println ("Version of Netica-J running: " +
                      Environ.getDefaultEnviron().getVersionString());

public void setArgumentChecking (
 int  setting 
) throws NeticaException
Sets the level to which Netica checks all arguments you pass it (one of NO_CHECK, QUICK_CHECK, REGULAR_CHECK, COMPLETE_CHECK).

Whenever a Netica API method is called, its arguments may be automatically checked for validity. Call this method anytime to adjust the degree of checking Netica does until it is called next.

setting should be one of:
NO_CHECK    No checking
QUICK_CHECK    Only checks things that can be checked very quickly
REGULAR_CHECK    Regular checking
COMPLETE_CHECK    Exhaustively checks everything.
Normally during development, the REGULAR_CHECK setting is used. For debugging, the setting can temporarily be changed to COMPLETE_CHECK, but that will run too slowly for most regular development. Once development is complete, production versions would normally have a setting of QUICK_CHECK ( NO_CHECK is discouraged, since it isn't much faster, but its also a possibility), but they may occasionally temporarily change it to REGULAR_CHECK in order to do user input checking.

Parameters:
int    setting    The new level of argument checking desired.

Version:

This method is available in all versions.
In the C Version of the API, this function is named ArgumentChecking_ns.
See Also:
getArgumentChecking    Retrieves value


public void setCaseFileDelimChar (
 char  newChar 
) throws NeticaException
Sets the symbol used to separate data fields in a case file being created by Netica.

For newchar, pass one of tab ('\t'), space (' ') or comma (',').

Whole cases are always separated by a line end (i.e., a carriage return, a newline, or both).

newchar will only be used by Netica for creating case files; while reading them it will understand any of the above choices.

Parameters:
char    newchar    The new character to be used.

Version:

Versions 1.18 and later have this method.
In the C Version of the API, this function is named SetCaseFileDelimChar_ns.
See Also:
setMissingDataChar    Set the character used to indicate missing data
writeFindings    The method that uses the file delimiter character
getCaseFileDelimChar    (inverse method) Get the current character used for this purpose

Example:
  Environ env = Environ.getDefaultEnviron();
  char oldDelim = env.getCaseFileDelimChar();
  char oldMiss  = env.getMissingDataChar();
  env.setCaseFileDelimChar (',');
  env.setMissingDataChar ((char) 0);    // 0 allowed only if delim char is comma
  // ... write the cases to file ...
  env.setCaseFileDelimChar (oldDelim);  // restore (if desired)
  env.setMissingDataChar (oldMiss);

public void setMemoryUsageLimit (
 double  maxMem 
) throws NeticaException
Call this method anytime to adjust the amount of memory that Netica is permitted to allocate for tables.

For maxMem pass the number of bytes allowed. For example, to limit memory usage to 100 Megabytes, pass 100e6.

If Netica does not have enough memory to complete an operation, it will gracefully limit its behavior, and throw an exception explaining the problem.

This method is especially useful when running on operating systems that will provide very large amounts of virtual memory. You may not want Netica to be allowed to claim such large amounts, since this can result in excessive hard-disk usage, and very slow behavior (also known as "system thrashing"). It is also useful in keeping Netica well-behaved, if it must share memory with other running programs.

Parameters:
double    maxMem    The new memory allocation limit

Version:

Versions 2.15 and later have this method.
In versions previous to 2.26, this method was named setMaxMemoryUsage.
In the C Version of the API, this function is named LimitMemoryUsage_ns.
See Also:
getMemoryUsageLimit    Retrieves value

Example:
  Environ.getDefaultEnviron().setMemoryUsageLimit (50e6); //limits table allocation space to 50MB

public void setMissingDataChar (
 char  newChar 
) throws NeticaException
Sets the symbol to be used for indicating missing data fields in a case file created by Netica. Data is "missing" when Netica has to provide the value for a node, and that node doesn't have a finding entered.

For newchar, pass one of asterisk ('*'), question mark ('?'), space (' '), or absent ((char) 0). It cannot be space or absent unless the delimiter symbol is a comma (see setCaseFileDelimChar).

newchar will only be used by Netica for creating case files; while reading them it will understand any of the above choices.

Parameters:
char    newchar    The new character to be used.

Version:

Versions 1.18 and later have this method.
In the C Version of the API, this function is named SetMissingDataChar_ns.
See Also:
setCaseFileDelimChar    Set the character used to separate data entries
writeFindings    The method that uses the missing data character
getMissingDataChar    (inverse method) Get the current character used for this purpose

Example:

public void setNetClass (
 Class  netClass 
) throws NeticaException

public void setNodeClass (
 Class  nodeClass 
) throws NeticaException

public double getMaxMemoryUsage ( ) throws NeticaException
Deprecated. use getMemoryUsageLimit() instead.


public void setMaxMemoryUsage (
 double  maxMem 
) throws NeticaException
Deprecated. use setMemoryUsageLimit (maxMem) instead.