com.edustructures.sifworks
Class ADK

java.lang.Object
  com.edustructures.sifworks.ADK

public class ADK
extends java.lang.Object

A global class representing the SIFWorks® ADK class framework.

Prior to calling any ADK methods or referencing any static constants, agents must first initialize the ADK by calling the static ADK.initialize method. The default initialize method loads all SIF Data Object (SDO) modules and selects the latest version of SIF as the default version used to render SIF Messages. If you use this method, ensure the sdoall.jar file is on the Java classpath. Other forms of the initialize method allow you to choose the specific SDO modules that are loaded as well as the version of SIF that will be the default for this agent session.

Version:

1.0

Field Summary

static int	DBG_ALL ADK debugging flag to enable all debugging output
static int	DBG_DETAILED Detailed debugging flags (exceptions, provisioning, messaging, detailed messaging, transport)
static int	DBG_EXCEPTIONS ADK debugging flag indicates whether exceptions are logged
static int	DBG_LIFECYCLE ADK debugging flag indicates whether agent startup/shutdown and initializaion activity is logged
static int	DBG_MESSAGE_CONTENT ADK debugging flag indicates whether message content is traced
static int	DBG_MESSAGING ADK debugging flag indicates whether Message Dispatching actions are traced
static int	DBG_MESSAGING_DETAILED ADK debugging flag indicates whether message headers are traced
static int	DBG_MESSAGING_EVENT_DISPATCHING ADK debugging flag indicates whether SIF_Event Message Dispatching actions are traced
static int	DBG_MESSAGING_PULL ADK debugging flag indicates whether SIF_SystemControl/SIF_GetMessage messages are traced
static int	DBG_MESSAGING_RESPONSE_PROCESSING ADK debugging flag indicates whether SIF_Response processing is traced
static int	DBG_MINIMAL Minimal debugging flags (exceptions, provisioning)
static int	DBG_MODERATE Moderate debugging flags (exceptions, provisioning, messaging, lifecycle)
static int	DBG_MODERATE_WITH_PULL Moderate debugging flags, with DBG_MESSAGING_PULL
static int	DBG_NONE ADK debugging flag to disable debugging output
static int	DBG_PROPERTIES ADK debugging flag indicates whether agent and zone properties are logged
static int	DBG_PROVISIONING ADK debugging flag indicates whether provisioning activity is traced.
static int	DBG_RUNTIME ADK debugging flag indicates whether Agent Runtime activity is traced.
static int	DBG_TRANSPORT ADK debugging flag indicates whether Transport setup is traced
static int	DBG_VERY_DETAILED Very detailed debugging flags (exceptions, provisioning, messaging, detailed messaging, transport, event dispatching, properties)
static int	debug The ADK debugging level determines which types of messages will be submitted to the Log4j environment by the class framework.
static java.lang.String	DEFAULT_LOG4J_PATTERN The default pattern used for writing to the logging framework
static java.lang.String	LOG_IDENTIFIER The Identifier that is used to identify the ADK itself for logging operations ("ADK")

Method Summary

static SIFDTD	DTD() Gets the default SIFDTD object for the version of SIF selected when the ADK was initialized.
static java.lang.String	getADKVersion() Gets the ADK build version
static SIFVersion	getLatestSupportedVersion(SIFVersion[] candidates) Returns the highest SIF_Version supported by the current instance of the ADK from the list of candidate versions.
static org.apache.log4j.Logger	getLog() Returns the root Log4j Category for the ADK.
static com.edustructures.sifworks.impl.ISIFPrimitives	getPrimitives() Gets a reference to the global ISIFPrimitives object used for SIF messaging
static ServerLog	getServerLog() Gets the root ServerLog instance for the ADK.
static SIFVersion	getSIFVersion() Gets the version of SIF used by the agent
static SIFVersion[]	getSupportedSIFVersions() Gets the versions of SIF supported by the ADK
static SIFFormatter	getTextFormatter() The SIFFormatter used by default for backwards-compatible non-typed APIs in the ADK, such as Element.getTextValue().
static com.edustructures.sifworks.impl.TransportPlugin	getTransportProtocol(java.lang.String protocol) Gets an installed transport protocol
static java.lang.String[]	getTransportProtocols() Gets the transport protocols available to agents.
static void	initialize() Initialize the ADK to use the latest version of SIF and all SIF Data Object (SDO) libraries.
static void	initialize(SIFVersion version, int sdoLibraries) Initialize the ADK to use the specified version of SIF.
static void	install(com.edustructures.sifworks.impl.TransportPlugin tp) Installs a transport protocol
static boolean	isInitialized() Has the ADK been initialized?
static boolean	isSIFVersionSupported(SIFVersion version) Determines if the specified version of SIF is supported by the ADK
static void	main(java.lang.String[] args) Displays the ADK Version
static java.lang.String	makeGUID() Utility method to generate a GUID for SIF Data Objects and messages.
static void	setLogFile(java.lang.String file) Redirects all log output to the specified file.
static void	setTextFormatter(SIFFormatter formatter) Sets the SIFFormatter used by default for rendering Text values of SIF Elements when mapping SIF Data directly to a string value.
static void	setVersion(SIFVersion version) Sets the version of SIF the ADK will use.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LOG4J_PATTERN

public static java.lang.String DEFAULT_LOG4J_PATTERN

The default pattern used for writing to the logging framework

LOG_IDENTIFIER

public static final java.lang.String LOG_IDENTIFIER

The Identifier that is used to identify the ADK itself for logging operations ("ADK")

See Also:

Constant Field Values

DBG_TRANSPORT

public static final int DBG_TRANSPORT

ADK debugging flag indicates whether Transport setup is traced

See Also:

Constant Field Values

DBG_MESSAGING

public static final int DBG_MESSAGING

ADK debugging flag indicates whether Message Dispatching actions are traced

See Also:

Constant Field Values

DBG_MESSAGING_EVENT_DISPATCHING

public static final int DBG_MESSAGING_EVENT_DISPATCHING

ADK debugging flag indicates whether SIF_Event Message Dispatching actions are traced

See Also:

Constant Field Values

DBG_MESSAGING_RESPONSE_PROCESSING

public static final int DBG_MESSAGING_RESPONSE_PROCESSING

ADK debugging flag indicates whether SIF_Response processing is traced

See Also:

Constant Field Values

DBG_MESSAGING_PULL

public static final int DBG_MESSAGING_PULL

ADK debugging flag indicates whether SIF_SystemControl/SIF_GetMessage messages are traced

See Also:

Constant Field Values

DBG_MESSAGING_DETAILED

public static final int DBG_MESSAGING_DETAILED

ADK debugging flag indicates whether message headers are traced

See Also:

Constant Field Values

DBG_MESSAGE_CONTENT

public static final int DBG_MESSAGE_CONTENT

ADK debugging flag indicates whether message content is traced

See Also:

Constant Field Values

DBG_PROVISIONING

public static final int DBG_PROVISIONING

ADK debugging flag indicates whether provisioning activity is traced. Note other debugging flags may cause provisioning messages to be logged even when this flag is not set.

See Also:

Constant Field Values

DBG_RUNTIME

public static final int DBG_RUNTIME

ADK debugging flag indicates whether Agent Runtime activity is traced.

See Also:

Constant Field Values

DBG_LIFECYCLE

public static final int DBG_LIFECYCLE

ADK debugging flag indicates whether agent startup/shutdown and initializaion activity is logged

See Also:

Constant Field Values

DBG_EXCEPTIONS

public static final int DBG_EXCEPTIONS

ADK debugging flag indicates whether exceptions are logged

See Also:

Constant Field Values

DBG_PROPERTIES

public static final int DBG_PROPERTIES

ADK debugging flag indicates whether agent and zone properties are logged

See Also:

Constant Field Values

DBG_ALL

public static final int DBG_ALL

ADK debugging flag to enable all debugging output

See Also:

Constant Field Values

DBG_NONE

public static final int DBG_NONE

ADK debugging flag to disable debugging output

See Also:

Constant Field Values

DBG_MINIMAL

public static int DBG_MINIMAL

Minimal debugging flags (exceptions, provisioning)

DBG_MODERATE

public static int DBG_MODERATE

Moderate debugging flags (exceptions, provisioning, messaging, lifecycle)

DBG_MODERATE_WITH_PULL

public static int DBG_MODERATE_WITH_PULL

Moderate debugging flags, with DBG_MESSAGING_PULL

DBG_DETAILED

public static int DBG_DETAILED

Detailed debugging flags (exceptions, provisioning, messaging, detailed messaging, transport)

DBG_VERY_DETAILED

public static int DBG_VERY_DETAILED

Very detailed debugging flags (exceptions, provisioning, messaging, detailed messaging, transport, event dispatching, properties)

debug

public static int debug

The ADK debugging level determines which types of messages will be submitted to the Log4j environment by the class framework. To eliminate all ADK-generated log messages set this value to 0. The default is DBG_VERY_DETAILED, which includes all debug flags except DBG_MESSAGE_CONTENT.

Method Detail

initialize

public static void initialize()
                       throws ADKException

Initialize the ADK to use the latest version of SIF and all SIF Data Object (SDO) libraries.

Calling this method when the ADK has already been initialized has no effect.

Throws:

ADKException - If the ADK cannot be initialized

initialize

public static void initialize(SIFVersion version,
                              int sdoLibraries)
                       throws ADKException

Initialize the ADK to use the specified version of SIF.

Calling this method when the ADK has already been initialized has no effect.

This method must be called at agent startup to initialize various resources of the ADK, establish global settings for the class framework, and set the default version of SIF to which all messages originating from the agent will conform.

Beginning with ADK 1.5.0, this method also configures the global ADK ServerLog instance with a logging module that will be inherited by the ServerLog of all zones. It installs a single logging module implementation: DefaultServerLogModule. The behavior of this module is to report SIF_LogEntry objects to the zone integration server via an Add SIF_Event message whenever ServerLog.reportLogEntry is called on a zone and the agent is running in SIF 1.5 or later. DefaultServerLogModule also echos server log messages to the zone's local Log4j Category so that agents do not need to duplicate logging to both the server and local agent log. If you want to install a custom ServerLogModule implementation -- or need to adjust the settings of the default module installed when the ADK is initialized -- call the ADK.getServerLog method to obtain a reference to the root of the ServerLog chain, then call its methods to add and remove modules. Refer to the ServerLog class for more information on server logging.

Parameters:

version - The version of SIF that will be used by the agent this session. Supported versions are enumerated by constants of the com.edustructures.SIFVersion class. Once initialized, the version cannot be changed.

sdoLibraries - One or more of the constants defined by the SDOLibrary class, identifying the SIF Data Object libraries to be loaded into memory (e.g. SDOLibrary.STUDENT | SDOLibrary.HR )

Throws:

ADKException - If the ADK cannot be initialized

ADKNotSupportedException - is thrown if the specified SIF version is not supported by the ADK, or if the sdoLibraries parameter is invalid

getLog

public static org.apache.log4j.Logger getLog()

Returns the root Log4j Category for the ADK.

Agents that wish to customize ADK logging may call this method to obtain the root Log4j Category.

Returns:

The Logger used by the ADK

getServerLog

public static ServerLog getServerLog()

Gets the root ServerLog instance for the ADK.

Agents that wish to customize ADK server-side logging may call this method to obtain the class framework's root ServerLog instance. Call any of the following methods to set up the chain of loggers that will be inherited by the Agent and all Zones:

• addLogger
• removeLogger
• clearLoggers
• getLoggers

Unlike client-side logging, server logging requires a connection to a Zone Integration Server. Because the current SIF 1.x infrastructure does not allow connections to servers independent of a zone, the logging methods of ServerLog are useful only when called within the context of a zone. Therefore, calling any of the logging methods on the ServerLog instance returned by this method will result in an IllegalStateException. This method is provided only to set up the ServerLog logger chain at the global ADK level.

Returns:

The ADK's root ServerLog instance

Since:

ADK 1.5

setLogFile

public static void setLogFile(java.lang.String file)
                       throws java.io.IOException

Redirects all log output to the specified file.

Parameters:

file - The log file

Throws:

java.io.IOException - If the File cannot be created or written to

isInitialized

public static boolean isInitialized()

Has the ADK been initialized?

Returns:

True if initialize() has already been called

setVersion

public static void setVersion(SIFVersion version)
                       throws ADKNotSupportedException

Sets the version of SIF the ADK will use. The version setting is global and therefore applies to all SIF messaging activity for all Agents instantiated in the current Java virtual machine.

Calling this method after agent initialization is not recommended.

Parameters:

version - The version of SIF that will be used by the agent. Supported versions are enumerated by constants of the com.edustructures.SIFVersion class

Throws:

ADKNotSupportedException - is thrown if the SIF version is not supported

getSupportedSIFVersions

public static SIFVersion[] getSupportedSIFVersions()

Gets the versions of SIF supported by the ADK

Returns:

An array of SIFVersion objects

getLatestSupportedVersion

public static SIFVersion getLatestSupportedVersion(SIFVersion[] candidates)

Returns the highest SIF_Version supported by the current instance of the ADK from the list of candidate versions. This method is helpful to agents during SIF_Request processing. A SIF_Request can contain multiple SIF_Versions in it.

Parameters:

candidates -

Returns:

The latest version supported by the ADK from the list of candidate versions

getTransportProtocols

public static java.lang.String[] getTransportProtocols()

Gets the transport protocols available to agents.

Returns:

An array of transport protocol strings (e.g. "http")

getTransportProtocol

public static com.edustructures.sifworks.impl.TransportPlugin getTransportProtocol(java.lang.String protocol)

Gets an installed transport protocol

Parameters:

protocol - The transport protocol name (e.g. "http", "https", etc.)

Returns:

The plugin class that represents this protocol, for internal use by the class framework

install

public static void install(com.edustructures.sifworks.impl.TransportPlugin tp)

Installs a transport protocol

Parameters:

tp - The Transport plugin to install

makeGUID

public static java.lang.String makeGUID()

Utility method to generate a GUID for SIF Data Objects and messages.

Returns:

A GUID

See Also:

GUIDGenerator

getADKVersion

public static java.lang.String getADKVersion()

Gets the ADK build version

Returns:

The ADK build version string (e.g. "1.0.4")

getSIFVersion

public static SIFVersion getSIFVersion()

Gets the version of SIF used by the agent

Returns:

The SIFVersion that the ADK is initialized to use

getTextFormatter

public static SIFFormatter getTextFormatter()

The SIFFormatter used by default for backwards-compatible non-typed APIs in the ADK, such as Element.getTextValue(). The default formatter used by the ADK is the SIF 1.x formatter for backwards compatibility. If you are* using the strongly-typed APIs, such as Element.getSIFValue(), this setting has no effect.

Returns:

the SIFFormatter used by default if no SIFVersion is provided

setTextFormatter

public static void setTextFormatter(SIFFormatter formatter)

Sets the SIFFormatter used by default for rendering Text values of SIF Elements when mapping SIF Data directly to a string value.

The default SIFFormatter used by the ADK is the formatter for SIF 1.5. This means that agents that were based on the 1.x version of the ADK will continue to get the SIF 1.x string version of data fields.

APIs that are affected by this setting include:
Element.getTextValue() (@link com.edustructures.sifworks.tools.mapping.StringMapAdaptor}

Parameters:

formatter - The default formatter to be used that translates native data types supported by SIF to their textual representation

isSIFVersionSupported

public static boolean isSIFVersionSupported(SIFVersion version)

Determines if the specified version of SIF is supported by the ADK

Parameters:

version - The version of SIF

Returns:

True if the specified version is supported by the ADK

DTD

public static SIFDTD DTD()

Gets the default SIFDTD object for the version of SIF selected when the ADK was initialized.

Returns:

The SIFDTD object for the version of SIF selected when the ADK was initialized.

getPrimitives

public static com.edustructures.sifworks.impl.ISIFPrimitives getPrimitives()

Gets a reference to the global ISIFPrimitives object used for SIF messaging

Returns:

The ISIFPrimitives implementation used by the ADK to send SIF Messages

main

public static void main(java.lang.String[] args)

Displays the ADK Version

Parameters:

args - The command line arguments are ignored