jsdai.lang
Class SdaiSession

java.lang.Object
  jsdai.lang.SdaiCommon
      jsdai.lang.SdaiSession

All Implemented Interfaces:

QuerySource

public final class SdaiSession

extends jsdai.lang.SdaiCommon

implements QuerySource

It is the main class to begin and end any usage of JSDAI. Only one SdaiSession object can exist at a time. An SdaiSession is started with openSession and ended with closeSession methods. The active session can be statically accessed with getSession method.

Conceptionally, the SdaiSession can be represented by the following EXPRESS entity:

ENTITY SdaiSession;
  sdaiImplementation : Implementation;
  knownServers       : SET [1:?] OF SdaiRepository;
  activeServers      : SET [1:?] OF SdaiRepository;
  activeModels       : SET [1:?] OF SdaiModel;
  dataDictionary     : OPTIONAL SchemaInstance;
  dataMapping        : OPTIONAL SchemaInstance;
INVERSE
  activeTransaction  : SdaiTransaction FOR owningSession;
END_ENTITY;

All attributes are read-only, and for each of them a corresponding get method is defined.

As it is documented in the description of class SdaiRepository, there exists a special repositories-directory which location is specified by the property "repositories" in the configuration file jsdai.properties. During execution of openSession method all the repositories found in this directory are made available for the user by including them into the set knownServers defined in the session. Some members of knownServers can be opened and, thus, can also be found in the set activeServers.

After openSession only the special repository with the name "SystemRepository" is opened. The "SystemRepository" is always the first member in activeServers and knownServers. The contents of this repository (SdaiModels and SchemaInstances) are read-only; an application is not allowed to modify them. The SdaiModels in "SystemRepository" contain either meta-descriptions of the supported EXPRESS schemas or mapping information between such schemas. The "SystemRepository" contains 2 SchemaInstances: with one all dictionary SdaiModels (data_dictionary) and with another all dictionary and mapping SdaiModels (data_mapping) are associated.

See Also:

"ISO 10303-22::7.4.1 sdai_session"

Field Summary

static java.lang.String	asterisk This field is for internal JSDAI use only.
static java.lang.String	COMP_MODEL_NAME The name of the reserved SdaiModel "MIXED_COMPLEX_TYPES_DICTIONARY_DATA".
static java.lang.String	DICT_MODEL_NAME The name of the reserved SdaiModel "SDAI_DICTIONARY_SCHEMA_DICTIONARY_DATA".
static java.lang.String	DICT_SCHEMA_NAME The name of the reserved SchemaInstance "SDAI_DICTIONARY_SCHEMA".
static java.lang.String	DICTIONARY_NAME_SUFIX Suffix of dictionary SdaiModel "_DICTIONARY_DATA"
static java.lang.String	DICTIONARY_SCHEMA_INSTANCE_NAME The name of the default SchemaInstance "SDAI_DICTIONARY_SCHEMA_INSTANCE" holding all dictionary SdaiModels.
static int	FALSE integer value for LOGICAL value FALSE.
static java.lang.String	MAPP_MODEL_NAME The name of the reserved SdaiModel "SDAI_MAPPING_SCHEMA_DICTIONARY_DATA".
static java.lang.String	MAPP_SCHEMA_NAME The name of the reserved SchemaInstance "SDAI_MAPPING_SCHEMA".
static java.lang.String	MAPPING_NAME_SUFIX Suffix of dictionary SdaiModel with mapping data "_MAPPING_DATA"
static java.lang.String	MAPPING_SCHEMA_INSTANCE_NAME The name of the default SchemaInstance "SDAI_MAPPING_SCHEMA_INSTANCE" holding all mapping and related dictionary SdaiModels
static int	TRUE integer value for LOGICAL value TRUE.
static int	UNKNOWN integer value for LOGICAL value UNKNOWN.

Method Summary

void	addLoggingListener(SdaiListener listener) Adds SdaiListener extending java.util.EventListener to a special aggregate of SDAI listeners receiving SDAI logging events.
void	closeSession() Terminates this SdaiSession.
static void	convertMapping(MappingContext mappingContext) Converts target (AIM) population by invoking underlying AIM2ARM algorithm.
java.lang.String	convertRepoName(java.lang.String name) Converts a given String to a string that may be used as a repository name.
SdaiRepository	createRepository(java.lang.String repository_name, java.lang.Object location) Creates a new repository and adds it to knownServers (but not to activeServers what means that the repository returned is closed).
void	enableLogging(boolean enable) Starts recording changes made to the entity instances in the log for subsequent undo/redo operations.
void	endUndoGroup() Ends recording changes (made to the entity instances) in the current group.
void	endUndoGroup(java.lang.Object listenerArgument) Ends recording changes (made to the entity instances) in the current group.
static jsdai.dictionary.EData_type	findDataType(java.lang.String name, java.lang.Class schema) This method is for internal JSDAI use only.
jsdai.dictionary.ESchema_definition	findSchemaDefinition(java.lang.String name) Given schema name, returns definition of the Express schema with this name.
ASdaiModel	getActiveModels() Returns SdaiModels currently being accessed in the session.
ASdaiRepository	getActiveServers() Returns the aggregate containing all repositories currently open in this SdaiSession.
SdaiTransaction	getActiveTransaction() Returns the transaction currently available in the session.
AEntity	getClipboard() Returns a clipboard - a globally available aggregate for all JSDAI applications running on the same JVM.
java.lang.Class	getComplexEntityClass(java.lang.Class[] types, java.lang.Class schema) Finds the entity class for a complex entity data type with two or more leaf entity data types.
jsdai.dictionary.EEntity_definition	getComplexEntityDefinition(jsdai.dictionary.EEntity_definition[] types, jsdai.dictionary.ESchema_definition schema) Finds the entity definition for a complex entity data type with two or more leaf entity data types.
java.lang.String	getDataBaseBridge() Returns SQL bridge connection URL
SchemaInstance	getDataDictionary() Returns the SchemaInstance with which all data dictionary SdaiModels are associated.
SchemaInstance	getDataMapping() Returns the SchemaInstance with which all SdaiModels with dictionary and mapping data are associated.
ASdaiRepository	getKnownServers() Returns the aggregate containing all repositories currently available in this SdaiSession.
static java.lang.String	getLicensee() Returns the name of the person or organization to whom a licence is granted.
static java.io.PrintWriter	getLogWriter() Returns the static logging/tracing PrintWriter that can be used during any SdaiSession.
java.io.PrintWriter	getLogWriterSession() Returns the logging/tracing PrintWriter that is associated with the current Object of SdaiSession.
jsdai.mapping.ASchema_mapping	getMappings(jsdai.dictionary.ESchema_definition schema) Returns the schema_mappings of AIM schema.
ASdaiModel	getQuerySourceDomain() Returns domain in which to perform a search.
jsdai.query.SerializableRef	getQuerySourceDomainRef()
jsdai.query.SerializableRef	getQuerySourceInstanceRef()
AEntity	getQuerySourceInstances() Returns starting instances which serve as the first input instance set for a query.
SdaiRepository	getRepositoryByRef(jsdai.query.SerializableRef repositoryRef) Returns remote SdaiRepository using specified repository reference.
static java.lang.String	getRepositoriesPath() Returns the pathname string of the local directory containing subdirectories for different repositories and some additional information.
SdaiContext	getSdaiContext() Returns the default context of this session.
Implementation	getSdaiImplementation() Returns the instance of class Implementation containing the general characteristics of JSDAI.
static java.lang.String	getSerialNumber() Returns the serial number of JSDAI.
static SdaiSession	getSession() Returns the session.
SdaiRepository	getSystemRepository() Returns a special repository with the name "SystemRepository".
void	importClearTextEncoding(java.io.InputStream sourceLocation, SdaiRepository destinationLocation) Imports an exchange structure (part21 file) into an existing repository submitted through the second method's parameter.
SdaiRepository	importClearTextEncoding(java.lang.String name, java.lang.Object source_location, java.lang.Object destination_location) Creates a new repository and imports an exchange structure (part21 file) into it.
ASchemaInstance	importClearTextEncoding(java.lang.String sourceLocation, SdaiRepository targetRepo) Imports an exchange structure (part21 file) into an existing repository submitted through the second method's parameter.
boolean	isModified() Informs if at least one repository available in this session is modified.
boolean	isRedoGroupAvailable() Informs whether the redo operation is available for at least one group of recorded changes.
boolean	isUndoGroupAvailable() Informs whether the undo operation is available for at least one group of recorded changes.
void	linkDataBaseBridge(java.lang.String bridgeURL, java.lang.String user, char[] password) Links SQL Bridge and makes remote repositories available in aggregate of known_servers, which is accessible through getKnownServers method.
SdaiRepository	linkRepository(java.lang.String name, java.lang.String location) Links an already existing SdaiRepository outside of this SdaiSession (external) to knownServers (but not to activeServers what means that the repository returned is closed).
java.util.Properties	loadApplicationProperties(java.lang.Class identification) Returns Properties table for an application specified by a parameter of type Class.
void	lock(ASdaiRepository repositories, ASchemaInstance schInstances, ASdaiModel models, int maxwait) Locks specified remote SdaiRepositories, SchemaInstances, and SdaiModels in exclusive mode on JSDAI-DB.
SdaiQuery	newQuery(org.w3c.dom.Document querySpec) Creates and returns a new SdaiQuery.
SdaiQuery	newQuery(org.w3c.dom.Element el) Creates and returns a new SdaiQuery
static SdaiSession	openSession() Commences a new SdaiSession.
static void	println(java.lang.String message) Prints a message to the static log Writer accessable for any SdaiSession.
void	printlnSession(java.lang.String message) Prints a message to the log Writer accessable only for the current Object of SdaiSession.
int	query(java.lang.String where, EEntity entity, AEntity result) This method is not implemented in current JSDAI version.
void	redoGroup(int groupCount) Performs redo operation for a specified number of groups.
void	redoGroup(int groupCount, java.lang.Object listenerArgument) Performs redo operation for a specified number of groups.
A_string	remoteRepositories(java.lang.String location) Finds a list of repositories on remote server.
void	removeLoggingListener(SdaiListener listener) Removes SdaiListener extending java.util.EventListener from the special aggregate of SDAI listeners receiving SDAI logging events.
static void	setLogWriter(java.io.PrintWriter out) Sets the static logging/tracing PrintWriter that can be used during any SdaiSession.
void	setLogWriterSession(java.io.PrintWriter out) Sets the logging/tracing PrintWriter that can be used during the current Object of SdaiSession.
void	setSdaiContext(SdaiContext context) Sets the default context of this session.
static void	setSessionProperties(java.util.Properties properties) Supplies SdaiSession properties.
SdaiTransaction	startTransactionReadOnlyAccess() Specifies the beginning of a sequence of read-only operations in this SdaiSession.
SdaiTransaction	startTransactionReadWriteAccess() Specifies the beginning of a sequence of read-write operations in this SdaiSession.
void	storeApplicationProperties(java.lang.Class identification, java.util.Properties properties, java.lang.String header) Writes the property list of the submitted Properties table to the properties file created for an application specified by a parameter of type Class.
void	switchToCommit(jsdai.query.SerializableRef commitRef) Switches remote repositories to specified commit point in history or to current state if null is passed as the parameter.
boolean	testActiveTransaction() Checks if the transaction is currently available in the session.
boolean	testDataDictionary() Checks whether this SDAI implementation supports data dictionary.
boolean	testDataMapping() Checks whether this SDAI implementation supports operations with mapping data.
java.lang.String	toString() Returns a description of this session as a String.
void	undoGroup(int groupCount) Performs undo operation for a specified number of groups.
void	undoGroup(int groupCount, java.lang.Object listenerArgument) Performs undo operation for a specified number of groups.
void	unlinkDataBaseBridge() Removal of all remote repositories from the aggregate "known_servers".
void	unlockAll() Removes all exclusive locks placed by this SdaiSession on remote SdaiRepositories, SchemaInstances, and SdaiModels.

Methods inherited from class java.lang.Object

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

Field Detail

asterisk

public static final java.lang.String asterisk

This field is for internal JSDAI use only. Applications shall not use it.

See Also:

Constant Field Values

TRUE

public static final int TRUE

integer value for LOGICAL value TRUE.

See Also:

Constant Field Values

FALSE

public static final int FALSE

integer value for LOGICAL value FALSE.

See Also:

Constant Field Values

UNKNOWN

public static final int UNKNOWN

integer value for LOGICAL value UNKNOWN.

See Also:

Constant Field Values

DICTIONARY_NAME_SUFIX

public static final java.lang.String DICTIONARY_NAME_SUFIX

Suffix of dictionary SdaiModel "_DICTIONARY_DATA"

See Also:

Constant Field Values

MAPPING_NAME_SUFIX

public static final java.lang.String MAPPING_NAME_SUFIX

Suffix of dictionary SdaiModel with mapping data "_MAPPING_DATA"

See Also:

Constant Field Values

DICTIONARY_SCHEMA_INSTANCE_NAME

public static final java.lang.String DICTIONARY_SCHEMA_INSTANCE_NAME

The name of the default SchemaInstance "SDAI_DICTIONARY_SCHEMA_INSTANCE" holding all dictionary SdaiModels.

See Also:

Constant Field Values

MAPPING_SCHEMA_INSTANCE_NAME

public static final java.lang.String MAPPING_SCHEMA_INSTANCE_NAME

The name of the default SchemaInstance "SDAI_MAPPING_SCHEMA_INSTANCE" holding all mapping and related dictionary SdaiModels

See Also:

Constant Field Values

DICT_MODEL_NAME

public static final java.lang.String DICT_MODEL_NAME

The name of the reserved SdaiModel "SDAI_DICTIONARY_SCHEMA_DICTIONARY_DATA".

See Also:

Constant Field Values

MAPP_MODEL_NAME

public static final java.lang.String MAPP_MODEL_NAME

The name of the reserved SdaiModel "SDAI_MAPPING_SCHEMA_DICTIONARY_DATA".

See Also:

Constant Field Values

COMP_MODEL_NAME

public static final java.lang.String COMP_MODEL_NAME

The name of the reserved SdaiModel "MIXED_COMPLEX_TYPES_DICTIONARY_DATA".

See Also:

Constant Field Values

DICT_SCHEMA_NAME

public static final java.lang.String DICT_SCHEMA_NAME

The name of the reserved SchemaInstance "SDAI_DICTIONARY_SCHEMA".

See Also:

Constant Field Values

MAPP_SCHEMA_NAME

public static final java.lang.String MAPP_SCHEMA_NAME

The name of the reserved SchemaInstance "SDAI_MAPPING_SCHEMA".

See Also:

Constant Field Values

Method Detail

getClipboard

public AEntity getClipboard()

Returns a clipboard - a globally available aggregate for all JSDAI applications running on the same JVM. Applications can access the clipboard aggregate, clear its contents, and add or remove instances of EEntity or other objects to or from it.

Returns:

the pre-existing general purpose clipboard aggregate.

getSdaiContext

public SdaiContext getSdaiContext()

Returns the default context of this session. The default context is used expression evaluation during legacy JSDAI method calls that have no SdaiContext parameter.

Returns:

Current default context

setSdaiContext

public void setSdaiContext(SdaiContext context)

Sets the default context of this session. The default context is used expression evaluation during legacy JSDAI method calls that have no SdaiContext parameter.

Parameters:

context - The new default context

getSession

public static SdaiSession getSession()

Returns the session. Only one SdaiSession object can exist at the same time, and this object can be accessed by this method.

Returns:

the only one SdaiSession or null if no session is open.

getSdaiImplementation

public Implementation getSdaiImplementation()
                                     throws SdaiException

Returns the instance of class Implementation containing the general characteristics of JSDAI. The SdaiSession has only one associated Implementation.

Returns:

the associated Implementation.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - VA_NSET, value not set.

getKnownServers

public ASdaiRepository getKnownServers()
                                throws SdaiException

Returns the aggregate containing all repositories currently available in this SdaiSession. This aggregate is called known servers.

Returns:

the aggregate of available repositories.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

See Also:

getActiveServers()

getActiveServers

public ASdaiRepository getActiveServers()
                                 throws SdaiException

Returns the aggregate containing all repositories currently open in this SdaiSession. This aggregate is called active servers.

Returns:

the aggregate of open repositories.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

See Also:

getKnownServers()

testDataDictionary

public boolean testDataDictionary()
                           throws SdaiException

Checks whether this SDAI implementation supports data dictionary. For JSDAI 2.0 and later versions this is always the case.

Returns:

true.

Throws:

SdaiException - SS_NOPN, session is not open.

testDataMapping

public boolean testDataMapping()
                        throws SdaiException

Checks whether this SDAI implementation supports operations with mapping data. For JSDAI 2.1 and later versions this is always the case.

Returns:

true.

Throws:

SdaiException - SS_NOPN, session is not open.

getDataDictionary

public SchemaInstance getDataDictionary()
                                 throws SdaiException

Returns the SchemaInstance with which all data dictionary SdaiModels are associated. This schema instance has name "SDAI_DICTIONARY_SCHEMA_INSTANCE" and belongs to the special repository with the name "SystemRepository". In JSDAI 2.0 and later versions this schema instance is always available.

Returns:

the SchemaInstance for the data dictionary.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - VA_NSET, value not set.

See Also:

getDataMapping()

getDataMapping

public SchemaInstance getDataMapping()
                              throws SdaiException

Returns the SchemaInstance with which all SdaiModels with dictionary and mapping data are associated. This schema instance has name "SDAI_MAPPING_SCHEMA_INSTANCE" and belongs to the special repository with the name "SystemRepository". In JSDAI 2.0 and later versions this schema instance is always available.

Returns:

the SchemaInstance for both dictionary and mapping data.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - VA_NSET, value not set.

See Also:

getDataDictionary()

getActiveModels

public ASdaiModel getActiveModels()
                           throws SdaiException

Returns SdaiModels currently being accessed in the session. Such SdaiModels must belong to opened repositories and must have either read-only or read-write access mode started.

Returns:

an aggregate containing all accessible SdaiModels.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

testActiveTransaction

public boolean testActiveTransaction()
                              throws SdaiException

Checks if the transaction is currently available in the session. The transaction, when started, makes access to all SdaiModels and SchemaInstances contained in the repositories of this session.

Returns:

true if an SdaiTransaction is available, false otherwise.

Throws:

SdaiException - SS_NOPN, session is not open.

See Also:

getActiveTransaction()

getActiveTransaction

public SdaiTransaction getActiveTransaction()
                                     throws SdaiException

Returns the transaction currently available in the session. For an SdaiSession there is either no or one SdaiTransaction which can be accessed by this method. If transaction is not available, then SdaiException VA_NSET is thrown.

Returns:

the SdaiTransaction of this session.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - VA_NSET, value not set.

See Also:

testActiveTransaction()

isModified

public boolean isModified()
                   throws SdaiException

Informs if at least one repository available in this session is modified. A repository is called modified if either at least one model or schema instance has been created, deleted or modified or some data outside repository contents were modified since the most recent commit or abort operation was performed.

Returns:

true if some repository of this session is modified, and false otherwise.

Throws:

SdaiException - SS_NOPN, session is not open.

getSystemRepository

public SdaiRepository getSystemRepository()
                                   throws SdaiException

Returns a special repository with the name "SystemRepository". This repository is opened automatically during openSession. However, its contents (SdaiModels and SchemaInstances) are read-only; an application is not allowed to modify them. The SdaiModels in "SystemRepository" contain either meta-descriptions of the supported EXPRESS schemas or mapping information between such schemas. The "SystemRepository" contains 2 SchemaInstances: with one all dictionary SdaiModels (data_dictionary) and with another all dictionary and mapping SdaiModels (data_mapping) are associated.

Returns:

special repository named "SystemRepository".

Throws:

SdaiException - SS_NOPN, session is not open.

toString

public java.lang.String toString()

Returns a description of this session as a String. It may be either "SdaiSession status: closed" or "SdaiSession status: open".

Returns:

a description of the session.

setLogWriter

public static void setLogWriter(java.io.PrintWriter out)

Sets the static logging/tracing PrintWriter that can be used during any SdaiSession. To disable it, this method should be applied with null passed to method's parameter.

Parameters:

out - the new logging/tracing PrintWriter.

See Also:

getLogWriter(), println(java.lang.String)

setLogWriterSession

public void setLogWriterSession(java.io.PrintWriter out)

Sets the logging/tracing PrintWriter that can be used during the current Object of SdaiSession. To disable it, this method should be applied with null passed to method's parameter.

Parameters:

out - the new logging/tracing PrintWriter.

See Also:

getLogWriter(), println(java.lang.String)

getLogWriter

public static java.io.PrintWriter getLogWriter()

Returns the static logging/tracing PrintWriter that can be used during any SdaiSession.

Returns:

the logging/tracing PrintWriter or null if it is disabled.

See Also:

setLogWriter(java.io.PrintWriter), println(java.lang.String)

getLogWriterSession

public java.io.PrintWriter getLogWriterSession()

Returns the logging/tracing PrintWriter that is associated with the current Object of SdaiSession.

Returns:

the logging/tracing PrintWriter or null if it is disabled.

See Also:

setLogWriter(java.io.PrintWriter), println(java.lang.String)

println

public static void println(java.lang.String message)
                    throws SdaiException

Prints a message to the static log Writer accessable for any SdaiSession. If null value is passed to the method's parameter, then SdaiException VA_NSET is thrown.

Parameters:

message - a log or tracing message.

Throws:

SdaiException - VA_NSET, value not set.

See Also:

getLogWriter(), setLogWriter(java.io.PrintWriter)

printlnSession

public void printlnSession(java.lang.String message)
                    throws SdaiException

Prints a message to the log Writer accessable only for the current Object of SdaiSession. If null value is passed to the method's parameter, then SdaiException VA_NSET is thrown.

Parameters:

message - a log or tracing message.

Throws:

SdaiException - VA_NSET, value not set.

See Also:

getLogWriter(), setLogWriter(java.io.PrintWriter)

getRepositoriesPath

public static java.lang.String getRepositoriesPath()
                                            throws SdaiException

Returns the pathname string of the local directory containing subdirectories for different repositories and some additional information. After opening the session these repositories become members of the set knownServers defined in the session.

Returns:

the pathname string of the repositories directory.

Throws:

SdaiException - SY_ERR, underlying system error.

getSerialNumber

public static java.lang.String getSerialNumber()

Returns the serial number of JSDAI. This method is deprecated.

Returns:

the serial number.

getLicensee

public static java.lang.String getLicensee()

Returns the name of the person or organization to whom a licence is granted. This method is deprecated.

Returns:

the name of the licensee.

setSessionProperties

public static void setSessionProperties(java.util.Properties properties)
                                 throws SdaiException

Supplies SdaiSession properties. This is an alternative way to providing properties through jsdai.properties file. This method should be called before the first SdaiSession is opened. If non null properties value is provided then jsdai.properties file is not loaded on session open.

This method is an extension of JSDAI, which is not a part of the standard.

Parameters:

properties - session properties. Refer to jsdai.properties for used properties. At least one property with the name repositories has to be available, which specifies the directory where SdaiRepositories are stored. This parameter can be null, which switched to default behavior of loading jsdai.properties file.

Throws:

SdaiException - SS_OPN is thrown in session was already opened.

Since:

4.0.0

openSession

public static SdaiSession openSession()
                               throws SdaiException

Commences a new SdaiSession. This is the first operation before any other SDAI activity can be started. More than one SdaiSession can be active at the same time. However only the first opened SdaiSession has the access to local SdaiRepositories in the set knownServers. JSDAI 2.2 and later versions allow within the same run of an application to re-open an SdaiSession as many times as it is needed.

This method initiates the set knownServers by putting into it "SystemRepository" and all repositories located in the special repositories-directory in the local file system. After execution of the method, "SystemRepository" always contains the following SdaiModels:

• "SDAI_DICTIONARY_SCHEMA_DICTIONARY_DATA" that contains information about the basic EXPRESS schema describing the structure of the data dictionary (this schema is underlying for each model containing dictionary data);
• "SDAI_MAPPING_SCHEMA_DICTIONARY_DATA" that is created to store the mapping data;
• "MIXED_COMPLEX_TYPES_DICTIONARY_DATA" that is created to store instances of complex entity data types whose partial entity types are taken from different EXPRESS schemas;

and the following SchemaInstances:

• "SDAI_DICTIONARY_SCHEMA_INSTANCE" with which all data dictionary models are associated;
• "SDAI_MAPPING_SCHEMA_INSTANCE" with which all models with dictionary and mapping data are associated.

Also, an insertion of specific data dictionary SdaiModels into "SystemRepository" can be managed. The needed models are specified by the property "jsdai.SXxx=some_string" in the configuration file jsdai.properties; here "xxx" is the package name in JSDAI library for which the corresponding data dictionary model will be created, and "some_string" is a two-level list of the names of EXPRESS schemas represented by the package "xxx". The names are written in upper case letters, exactly as in the instance of entity "file_schema" in the header of a Part-21 file. The list looks like AAA;BBB,CCC,DDD;EEE;FFF,GGG;
The top level of this list defines groups of schemas. Each group is covered by classes and interfaces of the package "xxx". A group may contain more than one schema. Their names in "some_string" are separated by commas. In the example above, the first group is AAA, the second is BBB,CCC,DDD, and so on. This strategy of alternative definition and grouping is useful in several situations including the following:

• it is possible to use non-standard extensions to specify extended AP schemas; in this case more than one schema may be given;
• it is possible to indicate subsets of some existing schema, usually by appending some suffix to its name;
• one and the same schema may be known by different names.

Also, it is permitted to drop the right-hand string (then it is assumed that some_string="") or to write any text not conforming the rules just defined. In this case a string at the right-hand side of the property statement is not used, and the schema represented by the data dictionary model created has the name xxx (which is taken from the left-hand side of the statement). The desribed mechanism allows to relate Part-21 files with libraries in JSDAI. The names representing some group in "some_string", for example, BBB,CCC,DDD can be listed in the header of a Part-21 file. This will mean that instances contained in this file are from the package "xxx".

Thus, for each JSDAI package specified using "jsdai.SXxx" property a dictionary model in "SystemRepository" is created. However, an explicit specification of dictionary models relevant for an application through jsdai.properties file is not mandatory. When needed, such models are created automatically. For example, when applying importClearTextEncoding method the exchange structure being imported may contain the name of the EXPRESS schema (in the header entity "file_schema", see "ISO 10303-21::9.2.3") for which no model in "SystemRepository" currently exists. In this case the needed model is created during execution of this method.

  Examples of property statements:
     jsdai.SAp203val=CCDCLGWIS;CONFIG_CONTROL_DESIGN,GEOMETRIC_VALIDATION_PROPERTIES_MIM;
     jsdai.SAutomotive_design=AUTOMOTIVE_DESIGN;AUTOMOTIVE_DESIGN_CC1;AUTOMOTIVE_DESIGN_CC2;
     jsdai.STopology_schema=anything

  Examples of FILE_SCHEMA instances:
     FILE_SCHEMA=(('CCDCLGWIS'));
     FILE_SCHEMA=(('CONFIG_CONTROL_DESIGN {099}','GEOMETRIC_VALIDATION_PROPERTIES_MIM{111}"));
     FILE_SCHEMA=(('AUTOMOTIVE_DESIGN_CC1 {1 2 10303 214-1 1 5 3}'));
     FILE_SCHEMA=(('TOPOLOGY_SCHEMA'));

Only two models within "SystemRepository" are automatically made accessible: "SDAI_DICTIONARY_SCHEMA_DICTIONARY_DATA" and "SDAI_MAPPING_SCHEMA_DICTIONARY_DATA". To start (read-only) access of any other data dictionary model, a transaction has to be started.

"SystemRepository" is opened automatically and only close session operation can close that repository.

Before opening SdaiSession JSDAI configuration information is searched. Configuration can be provided by invoking setSessionProperties method prior to first call to openSession or otherwise the property file jsdai.properties is searched in the following order:

1. If there is a system property jsdai.properties it is used as a directory where file jsdai.properties is searched. If system property is not given or file jsdai.properties does not exist in this directory then the next step is considered
2. User's current working directory (as returned by system property user.dir) is searched for file jsdai.properties. If file jsdai.properties does not exist in this directory then the next step is considered
3. User's home directory (as returned by system property user.home) is searched for file jsdai.properties. If file jsdai.properties does not exist in this directory then the next step is considered
4. Path of extension directory or directories (as returned by system property java.ext.dirs) is searched for file jsdai.properties. If jsdai.properties does not exist in this path then SdaiException.SY_ERR is thrown.

Returns:

the SdaiSession opened.

Throws:

SdaiException - SS_OPN, session open.

SdaiException - SS_NAVL, session not available.

SdaiException - SY_ERR, underlying system error.

See Also:

closeSession(), "ISO 10303-22::10.3.1 OpenSession", setSessionProperties(java.util.Properties)

closeSession

public void closeSession()
                  throws SdaiException

Terminates this SdaiSession. After execution of this method all JSDAI objects become not available. Particularly, all open repositories are closed. This method also deletes all temporary repositories.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

See Also:

openSession(), "ISO 10303-22::10.4.4 Close session"

startTransactionReadWriteAccess

public SdaiTransaction startTransactionReadWriteAccess()
                                                throws SdaiException

Specifies the beginning of a sequence of read-write operations in this SdaiSession.

Returns:

the read-write SdaiTransaction.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_EXS, transaction exists.

See Also:

startTransactionReadOnlyAccess(), SdaiTransaction.endTransactionAccessCommit(), SdaiTransaction.endTransactionAccessAbort(), "ISO 10303-22::10.4.6 Start transaction read-write access, 7.4.5 sdai_transaction, and 13.1.1 Levels of transaction"

startTransactionReadOnlyAccess

public SdaiTransaction startTransactionReadOnlyAccess()
                                               throws SdaiException

Specifies the beginning of a sequence of read-only operations in this SdaiSession.

Returns:

the read-only SdaiTransaction.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_EXS, transaction exists.

See Also:

startTransactionReadWriteAccess(), SdaiTransaction.endTransactionAccessCommit(), SdaiTransaction.endTransactionAccessAbort(), "ISO 10303-22::10.4.7 Start transaction read-only access, 7.4.5 sdai_transaction, and 13.1.1 Levels of transaction"

getComplexEntityDefinition

public jsdai.dictionary.EEntity_definition getComplexEntityDefinition(jsdai.dictionary.EEntity_definition[] types,
                                                                      jsdai.dictionary.ESchema_definition schema)
                                                               throws SdaiException

Finds the entity definition for a complex entity data type with two or more leaf entity data types. For such entities at least one "+" in their name can be observed.

The aggregate passed to the first method's parameter shall include all leaf entity data types required to uniquely identify the complex entity and may optionally include some supertypes of those leaf entity data types.

This method is not implemented in JSDAI 2.0. SdaiException FN_NAVL will be thrown if this method is invoked.

Parameters:

types - an aggregate containing leaf entity data types and possibly some of their supertypes.

schema - the EXPRESS schema where entity data types are defined or declared.

Returns:

the entity definition for a complex entity data type.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - ED_NDEF, entity definition not defined.

SdaiException - FN_NAVL, function not available.

See Also:

getComplexEntityClass(java.lang.Class[], java.lang.Class), "ISO 10303-22::10.9.1 Get complex entity definition"

getComplexEntityClass

public java.lang.Class getComplexEntityClass(java.lang.Class[] types,
                                             java.lang.Class schema)
                                      throws SdaiException

Finds the entity class for a complex entity data type with two or more leaf entity data types. In the names of such classes at least one "$" can be observed.

The aggregate passed to the first method's parameter shall include entity interfaces for all leaf entity data types required to uniquely identify the complex entity and may optionally include entity interfaces for some supertypes of those leaf entity data types.

This method is not implemented in JSDAI 2.0. SdaiException FN_NAVL will be thrown if this method is invoked.

Parameters:

types - an aggregate containing entity interfaces for leaf entity data types and possibly some of their supertypes.

schema - the EXPRESS schema where entity data types are defined or declared.

Returns:

the entity class for a complex entity data type.

Throws:

SdaiException - FN_NAVL, function not available.

See Also:

getComplexEntityDefinition(jsdai.dictionary.EEntity_definition[], jsdai.dictionary.ESchema_definition), "ISO 10303-22::10.9.1 Get complex entity definition"

findSchemaDefinition

public jsdai.dictionary.ESchema_definition findSchemaDefinition(java.lang.String name)
                                                         throws SdaiException

Given schema name, returns definition of the Express schema with this name. If schema with submitted name does not exist, then null is returned.

Parameters:

name - name of the schema.

Returns:

definition of the schema with the specified name.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

See Also:

SchemaInstance.getDefiningSchema()

linkRepository

public SdaiRepository linkRepository(java.lang.String name,
                                     java.lang.String location)
                              throws SdaiException

Links an already existing SdaiRepository outside of this SdaiSession (external) to knownServers (but not to activeServers what means that the repository returned is closed). Such a repository exists in the special repositories-directory or in the specified directory as SDAI file or it is a remote repository on a JSDAI-Server. This method also can be used to promote a degenerated repository (see class SdaiRepository) to the normal one. If method is applied by passing to its parameters the name and, possibly, the location of some repository which already exists in the current session, then it simply finds this repository in knownServers and returns it.

If null value or empty string is passed to the method's first parameter for the local repository, then SdaiException VA_NSET is thrown. If null value or empty string is passed to the method's first parameter for repository stored in SDAI file, then repository name is derived from location. If repository with the specified or derived name already exists and name parameter was not null, then repository with modified name (repository name plus sequence number) is linked. If name parameter was null, then SdaiException LC_NVLD is thrown.

Remote location string format is as follows:
//username:password@hostname:port or //username:password
Here the port number is optional.

This method is an extension of JSDAI, which is not a part of the standard.

Example:

    SdaiSession s = ...;
    SdaiRepository rep;
    rep = s.linkRepository("MyRepo0", null);
    rep = s.linkRepository("MyRepo1", "c:\\myrepos\\MyRepo.sdai");
    rep = s.linkRepository("", "c:\\MyRepo2.sdai");
    rep = s.linkRepository("MyRepo2", "//guest:passwd@192.123.22.11:1050");
    rep = s.linkRepository("MyRepo3", "//username:password@server.mydomain.com");
    rep = s.linkRepository("//testrep.server.lksoft.de", "//username:password@"); ?
    rep = s.linkRepository("//server.lksoft.de/MyRepo5", "//username:password@"); ?
    rep = s.linkRepository("//username:password@server.lksoft.de/MyRepo5", null);
    rep = s.linkRepository("//username:password@testrep.server.lksoft.de", null);

Parameters:

name - the name of the external repository to be linked.

location - a place where to find the external repository and, if needed, an access information like user-name and password.

Returns:

the SdaiRepository with the given name at the given location, either local or remote.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - RP_NEXS, repository does not exist.

SdaiException - RP_DUP, repository duplicate.

SdaiException - LC_NVLD, location is invalid.

SdaiException - VA_NSET, value not set.

See Also:

SdaiRepository.unlinkRepository()

createRepository

public SdaiRepository createRepository(java.lang.String repository_name,
                                       java.lang.Object location)
                                throws SdaiException

Creates a new repository and adds it to knownServers (but not to activeServers what means that the repository returned is closed). Such a repository is created either in the special repositories-directory or in the specified directory as SDAI file or as a remote repository on a JSDAI-Server.

• The first case happens if null is passed to the method's second parameter ("location"). Passing null value to the method's first parameter results in SdaiException VA_NSET. If the value for this parameter is an empty string "", then JSDAI creates a temporary repository with some default name. Each temporary repository is automatically deleted during execution of closeSession or openSession methods. The latter is possible if the last close session operation has ended abnormally or an application did not perform this operation. The value passed to the first parameter, provided nonempty, must obey the general rules imposed on the construction of valid repository names (see class SdaiRepository). If these rules are violated, then SdaiException VA_NVLD is thrown.
• The second case happens if path of SDAI file is passed to the method's second parameter ("location"). If the value for the first parameter is null or an empty string "", then JSDAI creates a repository with name derived from SDAI file name. If repository with the specified or derived name already exists, then repository with modified name (repository name plus sequence number) is created. SDAI file is used to store all repository data (repository, models and external data) in one file.
• The third case happens if remote location string is passed to the method's second parameter ("location"). Remote location string format is as follows:
  //username:password@hostname:port or //username:password
  Here the port number is optional.

This method is an extension of JSDAI, which is not a part of the standard.

Example:

    SdaiSession s = ...;
    SdaiRepository repo;
    // create local repositories
    repo = s.createRepository("MyRepo1", null);
    repo = s.createRepository("", null);

    // create repositories stored in SDAI files
    repo = s.createRepository("MyRepo2", "c:\\myrepos\\MyRepo.sdai");
    repo = s.createRepository("", "c:\\MyRepo2.sdai");

    // create remote repositories on JSDAI-Server
    repo = s.createRepository("MyRepo3", "//guest:passwd@192.123.22.11:1050");
    repo = s.createRepository("MyRepo4", "//username:password@server.mydomain.com");
    repo = s.createRepository("//testrep.server.lksoft.de", "//username:password@");
    repo = s.createRepository("//server.lksoft.de/MyRepo6", "//username:password@");

Parameters:

repository_name - the name of the newly created repository.

location - a location where to place the new repository.

Returns:

the SdaiRepository with the given name at the given location, either local or remote.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - RP_DUP, repository duplicate.

SdaiException - LC_NVLD, location is invalid.

SdaiException - VA_NSET, value not set.

SdaiException - VA_NVLD, value invalid.

SdaiException - SY_ERR, underlying system error.

See Also:

convertRepoName(java.lang.String)

importClearTextEncoding

public SdaiRepository importClearTextEncoding(java.lang.String name,
                                              java.lang.Object source_location,
                                              java.lang.Object destination_location)
                                       throws SdaiException

Creates a new repository and imports an exchange structure (part21 file) into it. Such a repository is created either in the special repositories-directory or in the specified directory as SDAI file or as a remote repository on a JSDAI-Server.

• The first case happens if null is passed to the method's third parameter ("destination_location").
• The second case happens if path of SDAI file is passed to the method's third parameter ("destination_location").
• The third case happens if remote location string is passed to the method's third parameter ("destination_location"). Remote location string format is as follows:
  //username:password@hostname:port or //username:password
  Here the port number is optional.

The repository is added to both knownServers and activeServers, thus it is open after execution of this method.

There are the following possibilities to choose the name of the repository:

1. The name is some nonempty string (passed to the first method's parameter). This string must obey the general rules imposed on the construction of valid repository names (see class SdaiRepository). If these rules are violated, then SdaiException VA_NVLD is thrown.
2. An empty string is passed for the name. In this case JSDAI creates a temporary repository with some default name. Each temporary repository is automatically deleted during execution of closeSession or openSession methods. The latter is possible if the last close session operation has ended abnormally or an application did not perform this operation.
3. The name parameter is null. In this case the name of the repository is taken from the entity file_name in the header of an exchange structure from which the encoding is imported. The string extracted from this entity, if needed, is converted to a string allowed to be a valid name of the repository (see class SdaiRepository). All characters before the first letter are deleted, and all illegal characters are replaced by underscores. If the resulting string is empty, then some default string as a repository name is used.

Before creating a new repository this method tries to find a degenerated repository with the same name (see class SdaiRepository) and, if an attempt is successfull, promotes it to the normal one.

For each data section in the exchange structure a separate SdaiModel in the repository is created. If the exchange structure contains only one data section, then the corresponding model gets name "default". Otherwise, the name of each model is taken from the parameters of the data section from which this model is constructed. Upon termination of the method each model contains all entity instances whose encoding is found in the corresponding data section.

This method automatically creates all needed data dictionary models, if any. Read-only access to these models is automatically started.

It should be noted that the method imports exchange structures in which all or some names of entities are presented in a short form. For example, any of the following cases for entity cartesian_point is apt:

• #1016=CARTESIAN_POINT('cp5',(0.0,0.0,-0.25));
• #1016=CRTPNT('cp5',(0.0,0.0,-0.25));

To identify an entity instance correctly from its short name, the latter must be defined in the data dictionary (provided by an Express compiler).

When importing part21 file it may happen that some complex instance in it is of entity type that is not defined or declared in the underlying schema. In this case method itself tries to replace this instance with an instance of known entity type that most fits to the missing type. To attributes of the substitute, which are common to those of the missing entity type, values taken from the part21 file are assigned. Attributes (if any) of the created instance, which are not defined in the missing entity type, are left unset. A user about this replacement operation is informed by the warning message issued.

This method is an extension of JSDAI, which is not a part of the standard.

Example:

    SdaiSession s = ...;
    SdaiRepository repo;
    repo = s.importClearTextEncoding(null,"myfile1.stp", null);
    repo = s.importClearTextEncoding("","myfile2.stp", null);
    repo = s.importClearTextEncoding("MyRepo3","myfile3.stp", null);
    repo = s.importClearTextEncoding("MyRepo4","myfile4.stp", "c:\\myrepos");

    // Stored in SDAI files
    repo = s.createRepository(null, "myfile5.pf", "MyRepo.sdai");
    repo = s.createRepository("MyRepo6", "myfile6.pf", "c:\\myrepos\\MyRepo.sdai");

    // On remote server side:
    repo = s.importClearTextEncoding("MyRepo7", "myfile7.pf", "//guest:passwd@192.123.22.11:1050");
    repo = s.importClearTextEncoding("MyRepo8", "myfile8.pf", "//user:secret@server.mydomain.com");
    repo = s.importClearTextEncoding("//MyRepo9.server.mydomain.com", "myfile9.pf", "//username:password@");
    repo = s.importClearTextEncoding("//server.mydomain.com/MyRepo10", "myfile10.pf", "//username:password@");

During import of an exchange structure (a part21 file) some checking and validation of the data contained in it is performed. This activity can be roughly classified as follows:

1. Detecting and reporting scanner errors. The error messages are:
   • "Only sign is specified."
   • "Integer number is too large to fit into long."
   • "Real literal without cyphers in an exponent."
   • "Unterminated string."
   • "Unterminated binary."
   • "Unterminated enumeration item."
   • "Incorrect enumeration item."
   • "Invalid user-defined entity name."
   • "Zero instance identifier."
   • "Incorrect instance identifier."
   • "Unmatched close of a comment."
   • "Comment not terminated."
   • "Lowercase is not allowed."
   • "Unexpected character."
   • "Unmatched input."
   • "Bad input stream initializer."
2. Detecting and reporting parser errors. The error messages are:
   • "Unexpected header entity.". It is thrown when some entity instance not allowed to appear in the header of the exchange structure is found.
   • "Value is incompatible with attribute type.". It is thrown when submitted values for attributes (which are all standard) of entity instances in the header are wrong. Also, in the case when at least one of the values after "DATA" keyword is incorrect (these values must be present when an exchange structure contains more than one data section).
   • "Insufficient number of values." This message appears for the header entities and "DATA" keyword similarly as "Value is incompatible with attribute type.".
   • "List contains improper item.". This message appears for the header entities and "DATA" keyword similarly as "Value is incompatible with attribute type.".
   • "List cannot be empty.". This message appears for the header entities similarly as "Value is incompatible with attribute type.".
   • "No express schema is provided.". It is thrown when an instance of the entity "file_schema" in the header does not provide the name of the express schema underlying for an exchange structure.
   • "Value in header is redefined or is entity instance identifier."
   • "Schema name in data section is inconsistent with the header.". The message appears when schema name specified for data section is missing in the list given by "file_schema" entity instance in the header.
   • "Parameter list in data section contains too many values.". This means that the number of values after "DATA" keyword is greater than two.
   • "Invalid token.". This message appears when a token incompatible with the grammar of the exchange structure is found. For example, "ENDSEC" is expected but the token considered is different.
   • "Entity name or right parenthesis is expected.". This means that in a data section after instance identifier and equality sign it should be either entity name (internal mapping case) or right parenthesis (external mapping case).
   • "Error: comma or right parenthesis expected.". The message may appear while processing an embedded list.
3. Checking the contents of the exchange structure. When reporting about errors, in addition to a message also some other information is printed: exchange structure, instance, entity, attribute, section name. The messages can be divided into the following groups:
   1. Reading header:
      • "Invalid section name in header's entities.". The message informs that section name in an instance of either entity 'section_language' or 'section_context' is wrong.
      • "Error: value for 'preprocessor_version' in FILE_NAME is missing, set to default."
      • "Error: value for 'originating_system' in FILE_NAME is missing, set to default."
      • "Error: value for 'authorization' in FILE_NAME is missing, set to default."
      • "Error: wrong section name in an instance of 'file_population'."
      • "Error: wrong comment in an instance of 'file_population'."
      • "Error: wrong or missing value of logical type in an instance of 'file_population'."
      • "Error: wrong or missing digit in an instance of 'file_population'."
      • "Error: wrong aggregate in an instance of 'file_population'."
   2. Reading instances:
      • "Duplicate instance identifier."
      • "Warning: user defined entity was encountered, instance was ignored."
      • "Warning: wrong ordering of partial entity values in complex instance."
      • "Error: Error: complex entity not available, please add it to .ce file and recreate your EXPRESS library"
      • "Error: unknown entity data types ". After the message the names of entity types of interest are listed.
      • "Error: entity data type in the schema not found."
   3. Reading values of entity instances:
      • "Error: value of integer type expected, replaced by unset value."
      • "Error: value of real type expected, replaced by unset value."
      • "Error: value of string type expected, replaced by null."
      • "Error: value of logical type expected, replaced by unset value."
      • "Error: value of boolean type expected, replaced by unset value."
      • "Error: wrong enumerated value, replaced by unset value."
      • "Error: value of enumeration type expected, replaced by unset value."
      • "Error: value of binary type expected, replaced by null."
      • "Error: reference to entity expected, replaced by null."
      • "Error: value of aggregate type expected, replaced by null."
      • "Error: aggregate as an element of an outer aggregate expected, replaced by null."
      • "Error: wrong type of value, value set to null."
      • "Error: wrong redefinition for integer, replaced by unset value."
      • "Error: wrong redefinition for double, replaced by unset value."
      • "Error: wrong redefinition for string, replaced by null."
      • "Error: wrong redefinition for logical, replaced by unset value."
      • "Error: wrong redefinition for boolean, replaced by unset value."
      • "Error: wrong redefinition for enumeration, replaced by unset value."
      • "Error: wrong redefinition for binary, replaced by null."
      • "Error: wrong redefinition for reference to instance, replaced by null."
      • "Error: wrong redefinition for value of select type, replaced by null."
      • "Error: insufficient number of values, replaced by unset value."
      • "Warning: discrepancies between physical file and express schema."
      • "Warning: unset value not allowed in SET, BAG, LIST (only in ARRAY)."
      • "Error: excessive value in ARRAY, it is ignored."
      • "Warning: reference to missing instance."
      • "Error: reference to an instance of wrong type, replaced by null."
      • "Error: TYPED_PARAMETER expected, value replaced by null."
      • "Warning: TYPED_PARAMETER missing, it was recovered."
      • "Error: number of values differs from the number of attributes."
      • "Error: number of values is less than the number of attributes."
      • "Error: number of values exceeds the number of attributes."
   4. Analysing of the strings:
      • "Incorrect string: "
      • "Invalid character in string: "
      • "Warning: control directive for the end of the sequence of characters from ISO 10646 is missing."

Parameters:

name - the name of the repository to which the data should be imported.

source_location - the location of the exchange structure, e.g. "c:\a_path\the_file.stp".

destination_location - the location where to place the new repository.

Returns:

the SdaiRepository with the data imported from the exchange structure.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - RP_DUP, repository duplicate.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NRW, transaction not read-write.

SdaiException - MO_DUP, SDAI-model duplicate.

SdaiException - VA_NVLD, value invalid.

SdaiException - SY_ERR, underlying system error.

See Also:

convertRepoName(java.lang.String), "ISO 10303-21: Implementation methods: Clear text encoding of the exchange structure", "Technical corrigendum 1 to ISO 10303-21", "Ammendment to ISO 10303-21"

importClearTextEncoding

public ASchemaInstance importClearTextEncoding(java.lang.String sourceLocation,
                                               SdaiRepository targetRepo)
                                        throws SdaiException

Imports an exchange structure (part21 file) into an existing repository submitted through the second method's parameter. It is not required for it to be empty: the new SdaiModels and SchemaInstances are simply added to the existing ones. The new schema instances constitute an aggregate that is returned by the method. In the case when a data section in the exchange structure being imported has the name which is already used by a model in the repository, the name of the new model corresponding to this data section is constructed by appending to it the letter "x", for example, data section "polytope" becomes a SdaiModel with the name "polytopex". An analogous operation is applied to the schema instances found in the exchange structure file. Other functionality of the method is the same as of its main variant importClearTextEncoding.

Parameters:

sourceLocation - the location of the exchange structure, e.g. "c:\a_path\the_file.stp".

targetRepo - the repository where to import the data from the exchange structure.

Returns:

the ASchemaInstance with the schema instances created or imported from the exchange structure.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NRW, transaction not read-write.

SdaiException - SY_ERR, underlying system error.

See Also:

"ISO 10303-21: Implementation methods: Clear text encoding of the exchange structure", "Technical corrigendum 1 to ISO 10303-21", "Ammendment to ISO 10303-21", importClearTextEncoding(String, Object, Object)

importClearTextEncoding

public void importClearTextEncoding(java.io.InputStream sourceLocation,
                                    SdaiRepository destinationLocation)
                             throws SdaiException

Imports an exchange structure (part21 file) into an existing repository submitted through the second method's parameter. The repository is required to be empty. This method is applicable when the location of the exchange structure file is remote and the data from it are supplied through the InputStream (the first parameter of the method). Other functionality of the method is the same as of its main variant importClearTextEncoding.

Parameters:

sourceLocation - the location of the exchange structure.

destinationLocation - the repository where to import the data from the exchange structure.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - TR_NEXS, transaction does not exist.

SdaiException - TR_NRW, transaction not read-write.

SdaiException - MO_DUP, SDAI-model duplicate.

SdaiException - SY_ERR, underlying system error.

See Also:

"ISO 10303-21: Implementation methods: Clear text encoding of the exchange structure", "Technical corrigendum 1 to ISO 10303-21", "Ammendment to ISO 10303-21", importClearTextEncoding(String, Object, Object)

convertRepoName

public java.lang.String convertRepoName(java.lang.String name)
                                 throws SdaiException

Converts a given String to a string that may be used as a repository name. All characters before the first letter are deleted, and all illegal characters are replaced by underscores. This resulting string obeys the general rules imposed on the construction of valid repository names (see class SdaiRepository).

This method is an extension of JSDAI, which is not a part of the standard.

Parameters:

name - the String asked to convert to valid repository name.

Returns:

the String converted to valid repository name.

Throws:

SdaiException

See Also:

createRepository(java.lang.String, java.lang.Object), importClearTextEncoding(java.lang.String, java.lang.Object, java.lang.Object)

findDataType

public static jsdai.dictionary.EData_type findDataType(java.lang.String name,
                                                       java.lang.Class schema)

This method is for internal JSDAI use only. Applications shall not use it.

remoteRepositories

public A_string remoteRepositories(java.lang.String location)
                            throws SdaiException

Finds a list of repositories on remote server.

Returns an A_string of the given name at the given location on remote server.

Example:
rep = session.remoteRepositories("//guest:passwd@server.lksoft.de")
rep = session.remoteRepositories("//guest:passwd@192.123.22.11:1050")
rep = session.remoteRepositories("//username:password@server.mydomain.com")

Parameters:

location - where to find the external repository and if needed access information like user-name and password.

Remote location format: //username:password@hostname:port
Port number is optional

Returns:

the A_string

Throws:

SdaiException - SS_NOPN, the session is closed

SdaiException - The location is invalid

getMappings

public jsdai.mapping.ASchema_mapping getMappings(jsdai.dictionary.ESchema_definition schema)
                                          throws SdaiException

Returns the schema_mappings of AIM schema.

Parameters:

schema - The AIM schema to return schema_mappings for

Returns:

ASchema_mapping containing schema_mappings

Throws:

SdaiException - if an error occurs in underlying JSDAI operations

loadApplicationProperties

public java.util.Properties loadApplicationProperties(java.lang.Class identification)
                                               throws SdaiException

Returns Properties table for an application specified by a parameter of type Class. If the required file containing a list of application properties does not exist, then an empty Properties table is returned.
Classes of package jsdai.lang are reserved by JSDAI to provide special JSDAI properties. The following special classes as a parameter can be specified:

jsdai.lang.SdaiSession (since JSDAI 4.0.1)

JSDAI-DB session properties. If the session is not linked to JSDAI-DB (by invoking method linkDataBaseBridge) the empty Properties is returned. Otherwise properties include at minimum properties named group-<name of the group> for each group the JSDAI-DB user which was specified invoking method linkDataBaseBridge belongs. The values of above mentioned properties correspond to Group Properties entered using Web Administration Tool.

This method is an extension of JSDAI, which is not a part of the standard.

Parameters:

identification - the class specifying an application.

Returns:

a table containing application properties.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

See Also:

storeApplicationProperties(java.lang.Class, java.util.Properties, java.lang.String)

storeApplicationProperties

public void storeApplicationProperties(java.lang.Class identification,
                                       java.util.Properties properties,
                                       java.lang.String header)
                                throws SdaiException

Writes the property list of the submitted Properties table to the properties file created for an application specified by a parameter of type Class.
Classes of package jsdai.lang are reserved by JSDAI to store special JSDAI properties.

This method is an extension of JSDAI, which is not a part of the standard.

Parameters:

identification - the class specifying an application.

properties - a table containing application properties.

header - a description of the property list.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, underlying system error.

See Also:

loadApplicationProperties(java.lang.Class)

enableLogging

public void enableLogging(boolean enable)
                   throws SdaiException

Starts recording changes made to the entity instances in the log for subsequent undo/redo operations. Modifications done on higher levels (SdaiModel, SdaiRepository, SchemaInstance) are not logged. The flow of records is divided into segments called groups. To close a group, method endUndoGroup() shall be used. The log file is automatically emptied during execution of commit and abort operations. Recording is stopped by submitting value false to the method. In this case the data are released, and undo/redo operations become disabled.

Parameters:

enable - true to start recording changes to the instances and false to stop recording.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

endUndoGroup

public void endUndoGroup()
                  throws SdaiException

Ends recording changes (made to the entity instances) in the current group. The next record automatically will be directed to a new group. The method also generates an object of SDAI logging event notifying the SDAI listeners about closing the current group of records.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

See Also:

endUndoGroup(Object listenerArgument)

endUndoGroup

public void endUndoGroup(java.lang.Object listenerArgument)
                  throws SdaiException

Ends recording changes (made to the entity instances) in the current group. The next record automatically will be directed to a new group. The method also generates an object of SDAI logging event notifying the SDAI listeners about closing the current group of records and supplies this event with an argument carrying user's information, which can be accessed by objects of classes implementing SdaiListener interface.

Parameters:

listenerArgument - an information provided to SDAI listeners receiving SDAI logging event.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

See Also:

endUndoGroup()

isUndoGroupAvailable

public boolean isUndoGroupAvailable()
                             throws SdaiException

Informs whether the undo operation is available for at least one group of recorded changes. That is, the answer is affirmative when the following two conditions are met:

• method enableLogging(boolean) was applied with parameter set at value true;
• at least one entity instance has been modified (created, deleted, substituted).

Returns:

true if undo operation is available; false otherwise.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.1.0

undoGroup

public void undoGroup(int groupCount)
               throws SdaiException

Performs undo operation for a specified number of groups. If this number, submitted through the method's parameter, is negative, then only one (the last) group undergoes undo operation. For each group, the method also generates an object of SDAI logging event notifying the SDAI listeners about completion of undo operation for that group of records.

Parameters:

groupCount - the number of groups (taken from the end of the list) for which the undo operation is asked to be performed.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

See Also:

undoGroup(int groupCount, Object listenerArgument)

undoGroup

public void undoGroup(int groupCount,
                      java.lang.Object listenerArgument)
               throws SdaiException

Performs undo operation for a specified number of groups. If this number, submitted through the method's parameter, is negative, then only one (the last) group undergoes undo operation. For each group, the method also generates an object of SDAI logging event notifying the SDAI listeners about completion of undo operation for that group of records and supplies this event with an argument carrying user's information, which can be accessed by objects of classes implementing SdaiListener interface.

Parameters:

groupCount - the number of groups (taken from the end of the list) for which the undo operation is asked to be performed.

listenerArgument - an information provided to SDAI listeners receiving SDAI logging event.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

See Also:

undoGroup(int groupCount)

isRedoGroupAvailable

public boolean isRedoGroupAvailable()
                             throws SdaiException

Informs whether the redo operation is available for at least one group of recorded changes. That is, the answer is affirmative when undo operation was executed for at least one group and, after that, no instance modification (deletion, creation) operation was performed.

Returns:

true if redo operation is available; false otherwise.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.1.0

redoGroup

public void redoGroup(int groupCount)
               throws SdaiException

Performs redo operation for a specified number of groups. If this number, submitted through the method's parameter, is negative, then only one (the first) group undergoes redo operation. For each group, the method also generates an object of SDAI logging event notifying the SDAI listeners about completion of redo operation for that group of records.

Parameters:

groupCount - the number of groups (taken from the beginning of the list) for which the redo operation is asked to be performed.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

See Also:

redoGroup(int groupCount, Object listenerArgument)

redoGroup

public void redoGroup(int groupCount,
                      java.lang.Object listenerArgument)
               throws SdaiException

Performs redo operation for a specified number of groups. If this number, submitted through the method's parameter, is negative, then only one (the first) group undergoes redo operation. For each group, the method also generates an object of SDAI logging event notifying the SDAI listeners about completion of redo operation for that group of records and supplies this event with an argument carrying user's information, which can be accessed by objects of classes implementing SdaiListener interface.

Parameters:

groupCount - the number of groups (taken from the beginning of the list) for which the redo operation is asked to be performed.

listenerArgument - an information provided to SDAI listeners receiving SDAI logging event.

Throws:

SdaiException - SS_NOPN, session is not open.

SdaiException - SY_ERR, an underlying system error occurred.

Since:

4.0.0

See Also:

redoGroup(int groupCount)

addLoggingListener

public void addLoggingListener(SdaiListener listener)
                        throws SdaiException

Adds SdaiListener extending java.util.EventListener to a special aggregate of SDAI listeners receiving SDAI logging events.

Parameters:

listener - a SdaiListener to be added.

Throws:

SdaiException

Since:

4.1.0

See Also:

removeLoggingListener(jsdai.lang.SdaiListener)

removeLoggingListener

public void removeLoggingListener(SdaiListener listener)
                           throws SdaiException

Removes SdaiListener extending java.util.EventListener from the special aggregate of SDAI listeners receiving SDAI logging events.

Parameters:

listener - SdaiListener to be removed.

Throws:

SdaiException

Since:

4.1.0

See Also:

addLoggingListener(jsdai.lang.SdaiListener)

linkDataBaseBridge

public void linkDataBaseBridge(java.lang.String bridgeURL,
                               java.lang.String user,
                               char[] password)
                        throws SdaiException

Links SQL Bridge and makes remote repositories available in aggregate of known_servers, which is accessible through getKnownServers method.

This method is an extension of JSDAI, which is not a part of the standard.

Example:

  SdaiSession s = ...;
  s.linkDataBaseBridge("//my.bridgeUrl.com", "user", "password".toCharArray());
  ...
  ASdaiRepository agRepositories = s.getKnownServers();
  

Parameters:

bridgeURL - a location where SQL Bridge is running prefixed with "//".

user - a user of SQL Bridge to use.

password - password stored as a character array.

Throws:

SdaiException - LC_NVLD, the location is invalid.

SdaiException - SY_ERR, underlying system error.

See Also:

getKnownServers(), JSDAI DB Extension

unlinkDataBaseBridge

public void unlinkDataBaseBridge()
                          throws SdaiException

Removal of all remote repositories from the aggregate "known_servers".

Throws:

SdaiException

getDataBaseBridge

public java.lang.String getDataBaseBridge()
                                   throws SdaiException

Returns SQL bridge connection URL

Throws:

SdaiException

switchToCommit

public void switchToCommit(jsdai.query.SerializableRef commitRef)
                    throws SdaiException

Switches remote repositories to specified commit point in history or to current state if null is passed as the parameter. This is an extension of SDAI. Commit reference is obtained from JSDAI-DB using remote queries in namespace jsdai:database: by querying entity commits which corresponds to commits table. Entity type commits is defined by this EXPRESS code:

 ENTITY commits;
   user_name : OPTIONAL STRING;
   time_stamp : STRING;
   app_comment : OPTIONAL STRING;
 END_ENTITY;
 

Attribute time_stamp conforms to this SimpleDateFormat string:
yyyy-MM-dd'T'HH:mm:ss.S
For querying also two more alternative time_stamp formats are allowed:
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd

This method is an extension of JSDAI, which is not a part of the standard.

Parameters:

commitRef - commit reference obtained using remote SDAI query or null which denotes current state

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

Since:

4.1.0

lock

public void lock(ASdaiRepository repositories,
                 ASchemaInstance schInstances,
                 ASdaiModel models,
                 int maxwait)
          throws SdaiException

Locks specified remote SdaiRepositories, SchemaInstances, and SdaiModels in exclusive mode on JSDAI-DB.

JSDAI-DB can place shared or exclusive locks on remote SdaiRepositories, SchemaInstances, and SdaiModels. JSDAI-DB locks objects in shared mode for certain JSDAI operations. Shared mode locks can be placed on the same object by more than one SdaiSession, however exclusive lock can be placed by at most one SdaiSession on the same object. In addition the lock can not be placed on an object if the lock of the opposite type already exists.

Exclusive locks are removed either by invoking method unlockAll or by ending remote session as a result of invoking unlinkRemoteRepositories or closeSession methods.

Shared locks are automatically placed by these operations on:

SdaiRepository

During run of deleteRepository, createModel, createSchemaInstance, and methods setting the header of SdaiRepository, or during run of delete, and deleteSdaiModel of contained SchemaInstances and SdaModels respectively on JSDAI-DB.

SchemaInstance

During run of addSdaiModel, removeSdaiModel, rename, delete, and methods setting the header of SchemaInstance on JSDAI-DB.

SdaiModel

From startReadWriteAccess or promoteSdaiModelToRW till endReadWriteAccess or reduceSdaiModelToRO operations.
During run of renameSdaiModel and deleteSdaiModel on JSDAI-DB.

This method is an extension of JSDAI, which is not a part of the standard.

Parameters:

repositories - an aggregate of SdaiRepositories to be locked or null if none of repositories needs to be locked.

schInstances - an aggregate of SchemaInstances to be locked or null if none of schema instances needs to be locked.

models - an aggregate of SdaiModels to be locked or null if none of models needs to be locked.

maxwait - maximum time in seconds to retry getting lock. The value of Integer.MAX_VALUE means that locking attempts should be retried indeterminately.

Throws:

SdaiException - SY_LOC, if requested lock can not be obtained within specified maximum time period.

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

Since:

4.1.0

See Also:

unlockAll(), SdaiRepository.getLockingUser(), SchemaInstance.getLockingUser(), SdaiModel.getLockingUser()

unlockAll

public void unlockAll()
               throws SdaiException

Removes all exclusive locks placed by this SdaiSession on remote SdaiRepositories, SchemaInstances, and SdaiModels.

This method is an extension of JSDAI, which is not a part of the standard.

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

Since:

4.1.0

See Also:

lock(jsdai.lang.ASdaiRepository, jsdai.lang.ASchemaInstance, jsdai.lang.ASdaiModel, int)

query

public int query(java.lang.String where,
                 EEntity entity,
                 AEntity result)
          throws SdaiException

This method is not implemented in current JSDAI version.

SdaiException FN_NAVL will be thrown if this method is invoked.

Specified by:

query in interface QuerySource

Parameters:

where - a String value

entity - an EEntity value

result - an AEntity value

Returns:

an int value

Throws:

SdaiException - FN_NAVL, function not available.

See Also:

"ISO 10303-22::10.4.14 SDAI query"

newQuery

public SdaiQuery newQuery(org.w3c.dom.Document querySpec)
                   throws SdaiException

Creates and returns a new SdaiQuery.

Parameters:

querySpec - is a XML document, which defines SdaiQuery

Returns:

The newly created SdaiQuery

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

newQuery

public SdaiQuery newQuery(org.w3c.dom.Element el)
                   throws SdaiException

Creates and returns a new SdaiQuery

Parameters:

el - is a XML element, which defines SdaiQuery

Returns:

The newly created SdaiQuery

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

getQuerySourceDomain

public ASdaiModel getQuerySourceDomain()
                                throws SdaiException

Description copied from interface: QuerySource

Returns domain in which to perform a search.

Specified by:

getQuerySourceDomain in interface QuerySource

Returns:

ASdaiModel containing the domain

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

getQuerySourceInstances

public AEntity getQuerySourceInstances()
                                throws SdaiException

Description copied from interface: QuerySource

Returns starting instances which serve as the first input instance set for a query.

Specified by:

getQuerySourceInstances in interface QuerySource

Returns:

AEntity containing the instances or null this aggregate consists all instances in query source domain

Throws:

SdaiException - if an error occurs during the operation or in underlying JSDAI operations

getQuerySourceInstanceRef

public jsdai.query.SerializableRef getQuerySourceInstanceRef()
                                                      throws SdaiException

Specified by:

getQuerySourceInstanceRef in interface QuerySource

Throws:

SdaiException

Since:

3.6.0

getQuerySourceDomainRef

public jsdai.query.SerializableRef getQuerySourceDomainRef()
                                                    throws SdaiException

Specified by:

getQuerySourceDomainRef in interface QuerySource

Throws:

SdaiException

Since:

3.6.0

getRepositoryByRef

public SdaiRepository getRepositoryByRef(jsdai.query.SerializableRef repositoryRef)
                                  throws SdaiException

Returns remote SdaiRepository using specified repository reference.

Parameters:

repositoryRef - SerializableRef used to refer to remote repository.

Returns:

SdaiRepository refered by specified repository reference.

Throws:

SdaiException - FN_NAVL, function not available.

SdaiException - SY_ERR, underlying system error.

See Also:

SdaiRepository.getSdaiModelByRef(SerializableRef), SdaiRepository.getSchemaInstanceByRef(SerializableRef), SdaiRepository.getInstanceByRef(SerializableRef)

convertMapping

public static void convertMapping(MappingContext mappingContext)
                           throws SdaiException

Converts target (AIM) population by invoking underlying AIM2ARM algorithm.

Parameters:

mappingContext - the mapping context containing conversion related information

Throws:

SdaiException - if an underlying JSDAI error occurs

Since:

3.6.0

See Also:

MappingContext, MappingPopulationCreator, JSDAI Mapping Extension