com.jadeworld.jade.rootschema
Class Application

java.lang.Object
  com.jadeworld.jade.rootschema.Object
      com.jadeworld.jade.rootschema.Application

public class Application
extends Object

The Application class provides a superclass of all user JADE application classes. Each user application is defined as an instance of the Application class. The Application class defines standard properties and methods for the running of any application.

Each time you create a new schema, an instance of the Application class is created for that schema. When you load a schema from a file and there is application data (in the .ddb forms definition file), JADE creates an instance of the Application class for each application defined in this file.

Each schema also has a subclass of the Application class. A transient instance of this class is automatically made available to the runtime copy of the application. To access this transient instance, use the app system variable in your method logic; for example, use app.name to access the name of the application. This transient instance is unique to a specific copy of the application. Changes made to the properties are retained until the application copy is terminated. (This data is therefore not available to other copies of the application.)

Transient objects that are automatically created by JADE cannot be shared, including the application object and exclusive collections. (For details about specifying the creation of transient objects that can be shared across threads, see create Instruction, in Chapter 1 of your JADE Developers Reference.)

Field Summary

Fields inherited from class com.jadeworld.jade.rootschema.Object

oid

Constructor Summary

Application()

Method Summary

java.util.Calendar	actualTime() Returns the current date and time of the JADE node.
java.util.Calendar	actualTimeServer() Returns the current date and time of the JADE server node.
char	applicationType() This contains the type of the application.
java.lang.String	appVersion() This is set at development time and serves only as documentation for the application.
int	clock() Returns the relative time in milliseconds since the operating system was started on the workstation that is executing the method.
java.lang.String	computerName() Returns the name of the device that executes the current method.
int	currentUTCBias(int location) Returns the current bias, in minutes, for local time translation on the node specified in the location parameter.
java.lang.String	dbPath() Returns the JADE database path.
java.lang.String	dbServerComputerName() Returns the computer name of the JADE database server.
java.lang.String	getIniFileName() Returns the full path and file name of the JADE initialization or configuration file for the current JADE node; for example: c:\jade62\system\jade.ini
java.lang.String	getJadeInstallDir() Returns the directory in which the JADE binaries are installed; for example: c:\jade62\bin
Application	getPersistentApp() Returns a reference to the persistent application from which the transient instance of the receiver was created.
Process	getProcess() Returns a reference to the JADE Process object associated with the application
java.lang.String	getProfileString(java.lang.String fileName, java.lang.String section, java.lang.String keyName, java.lang.String defaultValue) Retrieves a string from the specified section in a JADE initialization file.
java.lang.String	getSystemVersion() Returns a string containing the JADE system version; for example: 6.2.09
java.lang.String	getTempDir() Returns the temporary directory in which the JADE temporary files are located.
java.util.Calendar	getUTCTime() Returns the current UTC time for the machine on which the JADE node executes.
boolean	isAppRunning(java.lang.String schemaName, java.lang.String appName) Returns true if the application specified by the schemaName and appName parameters is running on the standard (fat) client within the same copy of jade.exe and returns false if the specified application is not running in the same copy of jade.exe.
boolean	isMultiUser() Returns true if the JADE application is running in multiuser mode.
boolean	isUnicode() Returns true if the JADE application is running with Unicode characters and strings or it returns false if the application is running with ANSI characters and strings.
boolean	isValidObject(Object obj) This is used to establish if the object specified in the obj parameter exists, by returning true.
boolean	isWebService() Returns true if the JADE application is running as a Web service or it returns false if the application is not running as a Web service.
java.lang.String	name() Contains the name specified in the Name text box of the Define Application dialog in the JADE development environment.
boolean	productionMode() Returns true if the database from which the JADE application is running has production mode set.
int	random(int range) Returns a random positive number in the range 0 through the value of the range parameter, inclusive.
int	random31(int seed, int range) Returns a random positive number in the range 0 through the value of the range parameter, inclusive.
java.math.BigDecimal	relativeMachineMicros() Returns a high-accuracy machine-relative time in microseconds (that is, millionths of a second).
java.math.BigDecimal	relativeMachineTime() Returns a high-accuracy machine-relative time in milliseconds.
void	repairCollection(ByRef<Collection> collRef) Removes invalid object references and fixes up dictionary keys in the collection specified in the coll parameter.
void	seedRandom(int seed) Initializes the random number generator.
java.lang.String	serverName() Returns the name of the server that is in use for the JADE application.
void	setAppVersion(java.lang.String appVersion) Sets the development-time application version.
boolean	setProfileString(java.lang.String fileName, java.lang.String section, java.lang.String keyName, java.lang.String string) Copies a string into the section of a JADE initialization file specified in the section parameter.
java.lang.String	userName() Returns the name of the current user as a string.

Methods inherited from class com.jadeworld.jade.rootschema.Object

changeObjectVolatility, creationTime, edition, equals, exclusiveLock, getClassNumberForObject, getInstanceIdForObject, getLockStatus, getName, getObjectStringForObject, getObjectVolatility, getOidString, getOidStringForObject, getPropertyValue, hashCode, hasMembers, isImportedObject, isKindOf, isLockedByMe, isObjectFrozen, isObjectNonSharedTransient, isObjectPersistent, isObjectSharedTransient, isObjectStable, isObjectTransient, isObjectVolatile, isSharedTransient, isSystemObject, isTransient, latestEdition, lock, makeObjectFrozen, makeObjectStable, makeObjectVolatile, reserveLock, sdeCauseEvent, sdsCauseEvent, setPropertyValue, sharedLock, toString, tryLock, unlock, updateObjectEdition

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Application

public Application()

Method Detail

actualTime

public java.util.Calendar actualTime()

Returns the current date and time of the JADE node.

Returns:

Current date/time as seen by the JADE system.

actualTimeServer

public java.util.Calendar actualTimeServer()

Returns the current date and time of the JADE server node.

Returns:

Current date/time on the JADE database server.

appVersion

public java.lang.String appVersion()

This is set at development time and serves only as documentation for the application.
The value is set by setAppVersion(java.lang.String).

Returns:

The development application version string.

setAppVersion

public void setAppVersion(java.lang.String appVersion)

Sets the development-time application version.

Parameters:

appVersion - The application version.

applicationType

public char applicationType()

This contains the type of the application.
For a Java application, this has a value of 'S', as a non-GUI JADE application.

Returns:

The JADE application type.

clock

public int clock()

Returns the relative time in milliseconds since the operating system was started on the workstation that is executing the method.
Note As the return value is limited by the size of an integer, the value returns to zero (0) after approximately 24 days.

This method provides a mechanism to obtain deltas (or differences) in time, taken at different points of execution; for example, as a means of timing the execution of a logic sequence.

Returns:

Relative time since the node was started.

computerName

public java.lang.String computerName()

Returns the name of the device that executes the current method.

Returns:

The name of the computer on which the JADE node is running.

currentUTCBias

public int currentUTCBias(int location)

Returns the current bias, in minutes, for local time translation on the node specified in the location parameter.

The bias is the difference in minutes between Coordinated Universal Time (UTC) and local time (that is, bias = UTC local time). As the bias is current, it includes any daylight saving adjustment in effect at the time the value is obtained. The location parameter values, provided by global constants in the ExecutionLocation category, are listed in the following table.

 Global Constant Integer Value Method is executed

 CurrentLocation 0 In the current location

 DatabaseServer 1 On the database server node

 PresentationClient 2 On the presentation client (applicable to applications running in thin client mode)

The current bias defaults to CurrentLocation (0) if you specify any value other than those listed in this table.

Returns:

The current UCT bias as minutes.

dbPath

public java.lang.String dbPath()

Returns the JADE database path. This is the value to which the persistence.xml property jade.database.path needs to be set.

Returns:

The JADE database path for the current JADE system.

dbServerComputerName

public java.lang.String dbServerComputerName()

Returns the computer name of the JADE database server.

Returns:

The JADE database server computer name.

getIniFileName

public java.lang.String getIniFileName()

Returns the full path and file name of the JADE initialization or configuration file for the current JADE node; for example:
c:\jade62\system\jade.ini

This is the value to which the persistence.xml property jade.database.configuration needs to be set.

Returns:

Jade initialization file path for the current JADE system.

getJadeInstallDir

public java.lang.String getJadeInstallDir()

Returns the directory in which the JADE binaries are installed;
for example:
c:\jade62\bin

Returns:

The directory of the JADE binaries.

getPersistentApp

public Application getPersistentApp()

Returns a reference to the persistent application from which the transient instance of the receiver was created.

Returns:

The persistence instance of the current Application subclass.

getProcess

public Process getProcess()

Returns a reference to the JADE Process object associated with the application

Returns:

The current JADE process.

getProfileString

public java.lang.String getProfileString(java.lang.String fileName,
                                         java.lang.String section,
                                         java.lang.String keyName,
                                         java.lang.String defaultValue)

Retrieves a string from the specified section in a JADE initialization file.
(See setProfileString(java.lang.String, java.lang.String, java.lang.String, java.lang.String), which copies the string into the specified section of an initialization file.)

The getProfileString method returns all sections if the value of the section parameter is null or an empty String, or all keys if the value of the keyName parameter is null or an empty String. The values are separated with a space.

You can use this method to retrieve a string from a two-level section name (prefixed with a unique identifier) within a JADE initialization file shared by multiple programs on the same host. For details, see Two-Level Section Names under Format of the JADE Initialization File, in your JADE Initialization File Reference. The following example shows the use of the getProfileString method to determine the server for the current JADE initialization file.

 String server;

 Application app = EntityAccess.getApp();

 server = app.getProfileString(app.getIniFileName(), "JadeClient","ServerName", null);

 System.out.println("server name is " + server);

Parameters:

fileName - Initialization file. If you set this parameter to windows, the win.ini file is used. If it does not contain a full path to the file, Windows searches for the file in the Windows directory.

section - Initialization file section containing the key (parameter) name.

keyName - Name of the key (parameter) whose associated string is to be retrieved.

defaultValue - Default value for the specified key if the key cannot be found in the initialization file.

Returns:

The specified part of the JADE initialization file.

getSystemVersion

public java.lang.String getSystemVersion()

Returns a string containing the JADE system version;
for example: 6.2.09

Returns:

The JADE system version.

getTempDir

public java.lang.String getTempDir()

Returns the temporary directory in which the JADE temporary files are located.

Returns:

The JADE temporary directory.

getUTCTime

public java.util.Calendar getUTCTime()

Returns the current UTC time for the machine on which the JADE node executes.

Returns:

Tthe current time in UTC as seen by the JADE node.

isAppRunning

public boolean isAppRunning(java.lang.String schemaName,
                            java.lang.String appName)

Returns true if the application specified by the schemaName and appName parameters is running on the standard (fat) client within the same copy of jade.exe and returns false if the specified application is not running in the same copy of jade.exe.

Parameters:

schemaName - JADE schema name of the application.

appName - JADE application name.

Returns:

true if the application is running.

isMultiUser

public boolean isMultiUser()

Returns true if the JADE application is running in multiuser mode. It returns false if the application is running in single user or read-only mode.

The persistence.xml property jade.database.multiuser determines this.

Returns:

true if the JADE application is running in multiuser mode.

isUnicode

public boolean isUnicode()

Returns true if the JADE application is running with Unicode characters and strings or it returns false if the application is running with ANSI characters and strings.

Returns:

true if the JADE application is a Unicode, or false if it is ANSI.

isValidObject

public boolean isValidObject(Object obj)

This is used to establish if the object specified in the obj parameter exists, by returning true. This method returns false if the specified object has been deleted.

Parameters:

obj - Java object with a matching JADE object.

Returns:

true if the JADE object equivalent of the Java parameter is a valid instance.

isWebService

public boolean isWebService()

Returns true if the JADE application is running as a Web service or it returns false if the application is not running as a Web service.

Returns:

false

name

public java.lang.String name()

Contains the name specified in the Name text box of the Define Application dialog in the JADE development environment.

This is the value to which the persistence.xml property jade.database.application needs to be set.

Returns:

The JADE application name.

productionMode

public boolean productionMode()

Returns true if the database from which the JADE application is running has production mode set.

Returns:

true if the JADE database has production mode set.

random

public int random(int range)

Returns a random positive number in the range 0 through the value of the range parameter, inclusive.
If the supplied range value exceeds 32,767, it is reset internally to 32,767. If the supplied range value is less than zero (0), it is internally reset to zero (0), which forces the random method to return to zero.

Note The sequence of generated random numbers is architecture-dependent.

Parameters:

range - The end of the range of random numbers to be produced.

Returns:

A pseudo-random integer within the specified range.

random31

public int random31(int seed,
                    int range)

Returns a random positive number in the range 0 through the value of the range parameter, inclusive.

Use this method to generate random numbers with a larger range of values compared to the random(int) method. In addition, the random31 method enables you to generate multiple sets of random numbers within a single application, by maintaining multiple values of the seed parameter.

The valid values for the seed parameter are in the range 1 through Max_Integer, inclusive. The valid values for the range parameter are in the range 0 through Max_Integer 1, inclusive.

If the supplied value of the seed parameter is not valid, JADE selects a new random seed value.
If the supplied value of the range parameter exceeds Max_Integer - 1 (that is, 2,147,483,646), it is internally reset to 2,147,483,646.
If the supplied value of the range parameter is less than zero (0), it is internally reset to zero (0), which forces the random31 method to return zero.

Parameters:

seed - The initial number to start the random sequence

range - The end of the range of random numbers to be produced.

Returns:

A pseudo-random number in the range 0 through max-integer.

relativeMachineMicros

public java.math.BigDecimal relativeMachineMicros()

Returns a high-accuracy machine-relative time in microseconds (that is, millionths of a second). This method is based on a hardware timer. (Internal ticks per second can vary, depending on hardware.)

The time is relative to the machine that is executing the method. This relative time value can wrap around after a period of machine up-time. The period of up-time is hardware-dependent.

As the maximum precision of the timer is 19 digits, you should use a Decimal[19] (or higher) precision decimal for storage and computation.

Returns:

Machine-relative time in microseconds.

relativeMachineTime

public java.math.BigDecimal relativeMachineTime()

Returns a high-accuracy machine-relative time in milliseconds. This method is based on a hardware timer. (Internal ticks per second can vary, depending on hardware.)

The time is relative to the machine that is executing the method. This relative time value can wrap around after a period of machine up-time. The period of up-time is hardware-dependent.

As the maximum precision of the timer is 19 digits, you should use a Decimal[19] (or higher) precision decimal for storage and computation.

Returns:

Machine-relative time in milliseconds.

repairCollection

public void repairCollection(ByRef<Collection> collRef)

Removes invalid object references and fixes up dictionary keys in the collection specified in the coll parameter. The repairCollection method enables you to perform an online repair of a collection while it is concurrently updated. The repairCollection method records progress information and information about entries that have been corrected, in the JADE jommsg.log file. This method iterates the collection specified in the coll parameter and performs the following actions.
Sets, arrays, and external key dictionaries:
Removes references to non-existent objects or references that are not type-compatible with the membership of the collection.
Member key dictionaries
Removes references to non-existent objects or references that are not type-compatible with the membership and checks that dictionary keys match the member keys. When they do not, the entry is removed and reinserted with the correct keys.

No action is taken with arrays of primitive types.

Note. Use the Application::repairCollection method only when you know that the collection is structurally sound and that only the entries in that collection are invalid.

Parameters:

collRef - The collection to be repaired.

seedRandom

public void seedRandom(int seed)

Initializes the random number generator. To set the random number generator with a new value, call this method, specifying the required value in the seed parameter.

Note Each application starts with a random seed value.

See also the random(int) and random31(int, int) methods.

Parameters:

seed - The initail value to initialize the random number generator.

serverName

public java.lang.String serverName()

Returns the name of the server that is in use for the JADE application.

Returns:

The JADE server computer name.

setProfileString

public boolean setProfileString(java.lang.String fileName,
                                java.lang.String section,
                                java.lang.String keyName,
                                java.lang.String string)

Copies a string into the section of a JADE initialization file specified in the section parameter. This method returns true if it succeeds in storing the specified string.

To retrieve a stored string, use getProfileString(java.lang.String, java.lang.String, java.lang.String, java.lang.String).

To remove a key parameter (keyName) from an initialization file, set the string parameter to ProfileRemoveKey (a global constant in the JadeProfileString category). To remove an entire section in an initialization file, set the keyName parameter to ProfileRemoveSection (a global constant in the JadeProfileString category).

You can use this method to copy a string to a two-level section name (prefixed with a unique identifier) within a JADE initialization file shared by multiple programs on the host. For details, see Two-Level Section Names under Format of the JADE Initialization File, in your JADE Initialization File Reference. However, you cannot use this method to update JADE initialization file parameter values specified on the command line. Attempts to do so return a value of false and the parameter values are unchanged.

Parameters:

fileName - Specifies the initialization file. If you set this parameter to windows, the win.ini file is used. If this parameter does not contain a full path to the file, Windows searches for the file in the Windows directory.

section - Specifies the initialization file section containing the key (parameter) name.

keyName - Specifies the name of the key (parameter) whose associated string is to be stored.

string - Specifies the string that is to be written to the file.

Returns:

true if the specified string could be set in the initialization file.

userName

public java.lang.String userName()

Returns the name of the current user as a string.

Returns:

The current JADE user name.