norsys.netica
Class NeticaError

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

public class NeticaError

extends java.lang.Object

A class that holds information on errors that occurred while Netica was attempting some operation (which become part of the NeticaException thrown), or on warnings or other status reports of successful Netica operations.

This class has no public constructor. You obtain instances from a NeticaException by calling NeticaException.getNeticaErrors, or, in the case of warnings, by calling the static method NeticaError.getWarnings.

Since:

2.08

Version:

2.20 - May 7, 2002

Field Summary

static int	ERROR_ERR Event occurred at "error" level - operation not properly finished, but no internal inconsistencies (e.g., user error, didn't finish process).
static int	FROM_DEVELOPER_CND Your program indicated the error.
static int	FROM_WRAPPER_CND The error did not occur within native Netica itself, but in the JAVA API wrapper layer.
static int	INCONS_FINDING_CND An inconsistent finding was entered into a Node.
static int	NOTHING_ERR Not anything.
static int	NOTICE_ERR Notice of something unusual.
static int	OUT_OF_MEMORY_CND System did not have enough memory to complete operation.
static int	REPORT_ERR Not an error, but a report of success.
static int	USER_ABORTED_CND User halted the method before it completed (not possible when using a Netica API version without the user interface).
static int	WARNING_ERR Event occurred at "warning" level - safe to proceed (e.g., user error, recovered okay).
static int	XXX_ERR Internal error, things left inconsistent - continuing could crash system.

Method Summary

int	getIdNumber() Returns the error number identifying this error.
java.lang.String	getMessage() Returns a message explaining the error.
int	getSeverity() Returns the severity level of this error (one of NOTHING_ERR, REPORT_ERR, NOTICE_ERR, WARNING_ERR, ERROR_ERR, or XXX_ERR).
static java.util.Vector	getWarnings(int severity) Deprecated.
static java.util.Vector	getWarnings(int severity, Environ env) Returns a vector of all the NeticaErrors in env that are at the severity level severity or higher.
boolean	isInCategory(int errcnd) Returns a boolean to indicate whether this error was caused by the condition errcnd.
java.lang.String	toString() Returns a readable string representation of this error.

Methods inherited from class java.lang.Object

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

Field Detail

NOTHING_ERR

public static final int NOTHING_ERR

Not anything. A good value for "severity" before anything has occurred. See getSeverity.

REPORT_ERR

public static final int REPORT_ERR

Not an error, but a report of success. See getSeverity.

NOTICE_ERR

public static final int NOTICE_ERR

Notice of something unusual. See getSeverity.

WARNING_ERR

public static final int WARNING_ERR

Event occurred at "warning" level - safe to proceed (e.g., user error, recovered okay). See getSeverity.

ERROR_ERR

public static final int ERROR_ERR

Event occurred at "error" level - operation not properly finished, but no internal inconsistencies (e.g., user error, didn't finish process). See getSeverity.

XXX_ERR

public static final int XXX_ERR

Internal error, things left inconsistent - continuing could crash system. See getSeverity.

OUT_OF_MEMORY_CND

public static final int OUT_OF_MEMORY_CND

System did not have enough memory to complete operation. See isInCategory and Environ.setMaxMemoryUsage.

USER_ABORTED_CND

public static final int USER_ABORTED_CND

User halted the method before it completed (not possible when using a Netica API version without the user interface). See isInCategory.

FROM_WRAPPER_CND

public static final int FROM_WRAPPER_CND

The error did not occur within native Netica itself, but in the JAVA API wrapper layer. See isInCategory.

FROM_DEVELOPER_CND

public static final int FROM_DEVELOPER_CND

Your program indicated the error. See isInCategory.

INCONS_FINDING_CND

public static final int INCONS_FINDING_CND

An inconsistent finding was entered into a Node. The finding did not agree with the model (Net) or with other findings according to the model. See isInCategory.

Method Detail

getIdNumber

public int getIdNumber()

Returns the error number identifying this error.

Version:

This method is available in all versions.
In the C Version of the API, this function is called ErrorNumber_ns.

See Also:

isInCategory		Returns a more general categorization of the error
getMessage		Returns a complete error message

getSeverity

public int getSeverity()

Returns the severity level of this error (one of NOTHING_ERR, REPORT_ERR, NOTICE_ERR, WARNING_ERR, ERROR_ERR, or XXX_ERR).

This returns an indicator of how serious the error is.

These are some of the values, in order from least to most serious, that may be returned:

NOTHING_ERR		Not anything (nothing to report)
REPORT_ERR		Not an error, but a report of success
NOTICE_ERR		Notice of something unusual
WARNING_ERR		Event occurred at "warning" level - requested operation was completed, but results are suspect in some way
ERROR_ERR		Event occurred at "error" level - requested operation was not properly finished, but no internal inconsistencies resulted
XXX_ERR		Internal error, things left inconsistent - continuing could crash system

The less serious errors have lower numerical value, so it is okay to use expressions like >= WARNING_ERR. In fact, it is better to use inequalities than equalities, since later some error levels may be inserted between those of the current list. NOTHING_ERR will always be the lowest, and XXX_ERR will always be the highest.

If the severity is XXX_ERR, then the event causing it is the fault of Netica, and you should contact Norsys about it (support@norsys.com), but if it is any of the others, you should be able to change your software to remove any problems.

Version:

This method is available in all versions.
In the C Version of the API, this function is called ErrorSeverity_ns.

See Also:

getIdNumber		Return the error's identification number
isInCategory		Return what kind of error it is

getMessage

public java.lang.String getMessage()

Returns a message explaining the error.

The message will start with the name of the Netica API method which was executing when the error occurred (the one you called, not any that are called internally), followed by a colon, and then a descriptive part. Generally the descriptive part is not just a generic message corresponding to the error number, but rather names the elements involved, and describes what went wrong.

Version:

This method is available in all versions.
In the C Version of the API, this function is called ErrorMessage_ns.

See Also:

getIdNumber		Returns the error's identification number
getSeverity		Returns how serious the error is
isInCategory		Returns what kind of error it is

isInCategory

public boolean isInCategory(int errcnd)

Returns a boolean to indicate whether this error was caused by the condition errcnd.

This is to discover the reason behind an error which has occurred. It groups together errors into broad classes.

For errcnd pass one of the conditions below, and the return value will be true iff that was a cause of the error. Note that some errors could have more than one cause.

Possible values for errcnd are:

OUT_OF_MEMORY_CND		System did not have enough memory to complete operation
INCONS_FINDING_CND		Inconsistent finding (only)
USER_ABORTED_CND		User halted the method before it completed (not possible when using a Netica API version without the user interface)
FROM_DEVELOPER_CND		Your program indicated the error by constructing a NeticaException
FROM_WRAPPER_CND		Error occurred in a language specific converter for VB, JAVA, or C++, etc.

Parameters:

int

errcnd

The ERROR_CATEGORY to be tested.

Version:

Versions 1.30 and later have this method.
In the C Version of the API, this function is called ErrorCategory_ns.

See Also:

getIdNumber		Return the error's identification number
getMessage		Return a complete error message
getSeverity		Return how serious the error is

getWarnings

public static java.util.Vector getWarnings(int severity,
                                           Environ env)
                                    throws NeticaException

Returns a vector of all the NeticaErrors in env that are at the severity level severity or higher.

For severity pass one of: REPORT_ERR, NOTICE_ERR, or WARNING_ERR.

If there are no warnings at the given severity level or higher, an empty Vector (not null) is returned.

Note, calling this method also removes all NeticaErrors currently in env, regardless of their severity level. This prevents the accumulation of the least important warnings.

The NeticaErrors returned will not contain any of level ERROR_ERR or XXX_ERR, since these result in NeticaExceptions being thrown when they occur.

Parameters:

int		severity		The level of errors and higher to retrieve; one of REPORT_ERR, NOTICE_ERR, or WARNING_ERR.
Environ		env		The Environment to scan for warnings.

Version:

This method is available in all versions.

Example #1:

    // First we create a cycle, and then detect the warning that it generates by
    // scanning the Environ.
    Environ env = node1.getNet().getEnviron();
    NeticaError.getWarnings( NeticaError.REPORT_ERR, env); //clears all warnings
    node1.addLink (node2);
    node2.addLink (node1);  // this creates a cycle of links
    Vector warnings = NeticaError.getWarnings( NeticaError.WARNING_ERR, env);
    Enumeration enum = warnings.elements();
    while (enum.hasMoreElements()) {
        NeticaError err = (NeticaError) enum.nextElement();
        if (err.getIdNumber() == 3200) { // cycle error id # is 3200 
            System.err.println ("Oops, created a cycle.");
        }
    }

Example #2:

    // We read a Net from Streamer "file", and then print out any warnings that 
    // were generated.
    Environ env = file.getEnviron();
    NeticaError.getWarnings( NeticaError.REPORT_ERR, env); //clears all warnings
    net = new Net (file); // a file read can generate warnings
    Vector warnings = NeticaError.getWarnings (NeticaError.WARNING_ERR, env);
    Enumeration enum = warnings.elements();
    while (enum.hasMoreElements()) {
        NeticaError err = (NeticaError) enum.nextElement();
        System.err.println ("*** WARNING ***  : " + ne);
    }

getWarnings

public static java.util.Vector getWarnings(int severity)
                                    throws NeticaException

Deprecated.

Returns a vector of all the NeticaErrors in the default Environ that are at the severity level severity or higher. Use getWarnings instead, as this method will be phased out.

Parameters:

int

severity

The level of errors and higher to retrieve; one of REPORT_ERR, NOTICE_ERR, or WARNING_ERR.

Version:

This method is available in all versions.

toString

public java.lang.String toString()

Returns a readable string representation of this error.

Version:

This method is available in all versions.

Example:

   try {
     net.setName ("This name is illegal");
   }
   catch (NeticaException ne) {
     ne.printStackTrace();
   }
   
   // would generate output similar to the below.  Note, a NeticaException's printStackTrace method
   // will call the toString() method of each NeticaError within it.
   **************  E R R O R  ***************
   ** ErrorNumber   = 5118
   ** ErrorSeverity = ERROR_ERR
   ** ErrorCategory =
   ** ErrorMessage  = SetNetName_bn: Name string passed is bad because 'This name is illegal' contains a space
   ******************************************

Overrides:

toString in class java.lang.Object