com.wrq.apptrieve.appconn
Interface AppConnModel

All Known Implementing Classes:
AppConnRejuvenationSession, AppConnSession

public interface AppConnModel

Interface to Model objects (entities, recordsets, attributes).

Using Filter Expressions

Some of the methods in the AppConn Java connector allow you to use filter expressions when fetching records from a recordset. The following is a description of the syntax you can use to build filter expressions:

condition_statement=condition_expression

You can use expressions on both the left and right sides of the condition statement. Be sure to enclose data in quotation marks.

Condition Expressions

Value Expressions A value expression can take any of the following:

Filter Expression Examples

patients.LastName <> "smith" All recordset fields in the patients recordset that are not "smith."

NOT (patients.LastName = "smith") All recordset fields in the patients recordset that are not "smith."

(SearchResults.LastName = "smith") and (SearchResults.FirstName = "Steven") All records in the SearchResults recordset with the last name "smith" and first name "Steven."

AccountNumbers.Accounts >= 10000 and AccountNumbers.Accounts <= 20000 All fields in the AccountNumbers recordset greater than or equal to 10000 and less than or equal to 20000.

(AccountNumbers.AcctNum >= variables.MinAccount) and (AccountNumbers.AcctNum <= variables.MaxAccount) AcctNum field in the AccountNumbers recordset greater than or equal to variable MinAccount and less than or equal to variable MaxAccount


Field Summary
static int ScrollEnd
          Used by moveCurrentRecordIndex(int).
static int ScrollHome
          Used by moveCurrentRecordIndex(int).
static int ScrollLineDown
          Used by moveCurrentRecordIndex(int).
static int ScrollLineUp
          Used by moveCurrentRecordIndex(int).
static int ScrollPageDown
          Used by moveCurrentRecordIndex(int).
static int ScrollPageUp
          Used by moveCurrentRecordIndex(int).
static int SyncToHost
          Used by setCurrentRecordIndex(int).
 
Method Summary
 void enableTerminalAttributes(boolean enable)
          Enables or disables the availability of terminal attributes when retrieving attribute or field data from the Host Integrator server.
 AppConnRecordSet fetchRecords(int maxRows, java.util.List fieldNames, java.lang.String filterExpression)
          Fetches up to max rows of data from the Host Integrator Server for the current recordset of the current entity.
 java.lang.String getAttributeAtCursor()
          Gets the name of the attribute at the current cursor position.
 java.util.List getAttributeLocations(java.util.List attributeNames)
          Gets a collection of ElementLocation objects for attributes of the current entity.
 AttributeMetaData getAttributeMetaData(java.lang.String entityName, java.lang.String attributeName)
          Gets metadata associated with an attribute.
 AppConnModelRecord getAttributes(java.util.List attributeNames)
          Gets the attributes of the current entity.
 java.lang.String getCurrentEntity()
          Gets the current entity (screen) of the legacy application.
 AppConnModelRecord getCurrentRecord()
          Fetches the current record in the current recordset.
 int getCurrentRecordIndex()
          Gets the index number of the current record in the current recordset.
 java.lang.String getCurrentRecordSetName()
          Gets the name of the current recordset.
 java.util.List getEntityAttributes(java.lang.String entityName)
          Gets the attribute names of an entity in the Host Integrator model.
 java.lang.String getEntityDescription(java.lang.String entityName)
          Gets the description for an entity in the Host Integrator model.
 java.util.List getEntityOperations(java.lang.String entityName)
          Gets the operation names of an entity in the Host Integrator model.
 java.util.List getEntityRecordSets(java.lang.String entityName)
          Gets the names of the recordsets for an entity in the Host Integrator model.
 java.util.List getFieldLocations(java.util.List fieldNames)
          Gets a collection of ElementLocation objects for fields of the current record in the current recordset of the current entity.
 FieldMetaData getFieldMetaData(java.lang.String entityName, java.lang.String recordSetName, java.lang.String fieldName)
          Gets metadata associated with a recordset field.
 java.lang.String getHomeEntityName()
          Gets the name of the home entity for the Host Integrator model.
 java.util.List getModelEntities()
          Gets the entity names of the Host Integrator model.
 java.util.List getModelVariableNames()
          Gets the names of all model variables in the Host Integrator model.
 java.util.Map getModelVariables()
          Gets the values of model variables in the Host Integrator model.
 OperationMetaData getOperationMetaData(java.lang.String entityName, java.lang.String operationName)
          Gets metadata associated with an operation.
 java.util.List getPatternLocations(java.util.List patternNames)
          Gets a collection of ElementLocation objects for patterns of the current entity.
 java.util.List getRecordSetLocations(java.util.List recordSetNames)
          Gets a collection of ElementLocation objects for recordSets of the current entity.
 RecordSetMetaData getRecordSetMetaData(java.lang.String entityName, java.lang.String recordSetName)
          Gets metadata associated with a recordset.
 VariableMetaData getVariableMetaData(java.lang.String variableName)
          Gets metadata associated with a variable.
 void insertRecord(java.util.Map record)
          Performs the insert operation for the current recordset.
 void insertRecords(java.util.List records)
          Performs the insert operation for the current recordset multiple times.
 void moveCurrentRecordIndex(int movement)
          Moves the current record index to a new position in the current recordset.
 AppConnModelRecord nextRecord(java.lang.String filterExpression)
          Finds and return a record in the current recordset using a filter expression.
 void performEntityOperation(java.lang.String operationName)
          Performs an operation on the current entity.
 java.lang.String processString(java.lang.String inStr)
          Calls the ProcessString event handler on the server.
 void selectCurrentRecord()
          Performs the selection operation for the current recordset.
 boolean selectRecordByFilter(java.lang.String filterExpression)
          Finds a record in the current recordset using a filter expression and perform its selection operation.
 boolean selectRecordByIndex(int index)
          Performs its selection operation on a record in the current recordset.
 void setAttributes(java.util.Map attributes)
          Sets the attributes in the current entity.
 void setAttributesDelayed(java.util.Map attributes, java.lang.String entityName)
          Sets the attributes of an entity.
 void setCurrentEntity(java.lang.String entityName)
          Sets the current entity.
 boolean setCurrentRecordIndex(int index)
          Changes the index number of the current record in the current recordset.
 void setCurrentRecordSetByName(java.lang.String recordSetName)
          Sets the current recordset by name.
 void setModelVariables(java.util.Map variables)
          Sets the values of variables in the Host Integrator model.
 void updateCurrentRecord(java.util.Map record)
          Changes the values of the current record in the current recordset.
 boolean updateRecordByFilter(java.util.Map record, java.lang.String filterExpression)
          Changes the values of a record in the current recordset.
 boolean updateRecordByIndex(java.util.Map record, int index)
          Changes the values of a record in the current recordset.
 int updateRecords(java.util.Map record, java.lang.String filterExpression)
          Changes the values of records in the current recordset.
 void waitForCondition(int timeout, java.lang.String expression, java.lang.String entityName)
          Waits for an expression to become true for an entity on the Host Integrator server.
 void waitForEntityChange(java.lang.String entityName, int timeout)
          Deprecated. Use of this method should be avoided, because it can sometimes result in a race condition.
 

Field Detail

ScrollHome

static final int ScrollHome
Used by moveCurrentRecordIndex(int).

See Also:
Constant Field Values

ScrollEnd

static final int ScrollEnd
Used by moveCurrentRecordIndex(int).

See Also:
Constant Field Values

ScrollLineUp

static final int ScrollLineUp
Used by moveCurrentRecordIndex(int).

See Also:
Constant Field Values

ScrollLineDown

static final int ScrollLineDown
Used by moveCurrentRecordIndex(int).

See Also:
Constant Field Values

ScrollPageUp

static final int ScrollPageUp
Used by moveCurrentRecordIndex(int).

See Also:
Constant Field Values

ScrollPageDown

static final int ScrollPageDown
Used by moveCurrentRecordIndex(int).

See Also:
Constant Field Values

SyncToHost

static final int SyncToHost
Used by setCurrentRecordIndex(int).

See Also:
Constant Field Values
Method Detail

enableTerminalAttributes

void enableTerminalAttributes(boolean enable)

Enables or disables the availability of terminal attributes when retrieving attribute or field data from the Host Integrator server. This method applies to subsequent getAttributes or fetchRecord method calls. Attributes are only retrieved if they are enabled at run-time with this method call and enabled in the model file for the entity or recordset.

Parameters:
enable - boolean - Set to true to enable terminal attribute retrieval
Throws:
MetaDataOnlyException - - if this is a metadata-only connection

fetchRecords

AppConnRecordSet fetchRecords(int maxRows,
                              java.util.List fieldNames,
                              java.lang.String filterExpression)
                              throws ApptrieveException
Fetches up to max rows of data from the Host Integrator Server for the current recordset of the current entity. If the number of rows to fetch is specified as 0 then the number of rows that will be returned is unlimited. The set of records returned begins with the first record following the current record. If the current record is before the first record in the recordset, searching starts with the first record.

For fetchRecords, the current record is the last record included in returned set of records.

If attributeNames is null, fetchRecords will return all fields for each record.

Parameters:
maxRows - int - The maximum number of rows that will be fetch
fieldNames - java.util.List - List of the field names to fetch from the entity
filterExpression - java.lang.String - An expression that qualifies the records to fetch
Returns:
com.wrq.apptrieve.appconn.AppConnRecordSet - the resulting records fetched from the Host Integrator server. If no records match the filterExpression, the method returns an AppConnRecordSet object containing no records.
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

getAttributeAtCursor

java.lang.String getAttributeAtCursor()
                                      throws ApptrieveException

Gets the name of the attribute at the current cursor position. Returns an empty string if the cursor is not currently within one of the defined entity attributes.

Returns:
java.lang.String - the attribute name
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

getAttributeMetaData

AttributeMetaData getAttributeMetaData(java.lang.String entityName,
                                       java.lang.String attributeName)
                                       throws AppConnException,
                                              ApptrieveException

Gets metadata associated with an attribute.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
attributeName - java.lang.String - Name of the attribute of the entity in the Host Integrator model
Returns:
com.wrq.apptrieve.appconn.AttributeMetaData - the metadata object for the entity attribute
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs

getAttributeLocations

java.util.List getAttributeLocations(java.util.List attributeNames)
                                     throws ApptrieveException

Gets a collection of ElementLocation objects for attributes of the current entity. If attributeNames is null, getAttributeLocations will return ElementLocation objects for all attributes of the entity.

Parameters:
attributeNames - java.util.List - List of attribute names to use in getting locations
Returns:
java.util.List - a List of ElementLocation objects, one for each attribute
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

getAttributes

AppConnModelRecord getAttributes(java.util.List attributeNames)
                                 throws ApptrieveException

Gets the attributes of the current entity. If attributeNames is null, getAttributes will return all attributes of the entity.

Parameters:
attributeNames - java.util.List - List of attribute names to get from the entity
Returns:
com.wrq.apptrieve.appconn.AppConnModelRecord - the attributes of the entity
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setAttributes(java.util.Map), setAttributesDelayed(java.util.Map, java.lang.String)

getCurrentEntity

java.lang.String getCurrentEntity()
                                  throws ApptrieveException

Gets the current entity (screen) of the legacy application.

Reasons for failure include:

  1. Server session has not been established.

Returns:
java.lang.String
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setCurrentEntity(java.lang.String)

getCurrentRecord

AppConnModelRecord getCurrentRecord()
                                    throws ApptrieveException

Fetches the current record in the current recordset.

Returns:
AppConnModelRecord - the current record. If there is no current record, the method returns an AppConnModelRecord object that has no data values and has the index number set to -1.
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
nextRecord(java.lang.String), setCurrentRecordIndex(int), getCurrentRecordIndex()

getCurrentRecordIndex

int getCurrentRecordIndex()
                          throws ApptrieveException
Gets the index number of the current record in the current recordset.

Returns:
int - the index of the current record
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setCurrentRecordIndex(int), getCurrentRecord()

getCurrentRecordSetName

java.lang.String getCurrentRecordSetName()
                                         throws ApptrieveException
Gets the name of the current recordset.

Returns:
String - the name of the current recordset
Throws:
ApptrieveException - - if there is no current recordset for
MetaDataOnlyException - - if this is a metadata-only connection the current entity or if a Host Integrator server error occurs.

getEntityAttributes

java.util.List getEntityAttributes(java.lang.String entityName)
                                   throws AppConnException,
                                          ApptrieveException

Gets the attribute names of an entity in the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.
  2. Invalid entity name.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
Returns:
java.util.List - a List of Strings, one for each attribute in the specified entity
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
See Also:
getModelEntities()

getEntityDescription

java.lang.String getEntityDescription(java.lang.String entityName)
                                      throws AppConnException,
                                             ApptrieveException

Gets the description for an entity in the Host Integrator model.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
Returns:
java.lang.String - The description string for the entity
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs

getEntityOperations

java.util.List getEntityOperations(java.lang.String entityName)
                                   throws AppConnException,
                                          ApptrieveException

Gets the operation names of an entity in the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.
  2. Invalid entity name.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
Returns:
java.util.List - a List of Strings, one for each operation
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
See Also:
getModelEntities()

getEntityRecordSets

java.util.List getEntityRecordSets(java.lang.String entityName)
                                   throws AppConnException,
                                          ApptrieveException

Gets the names of the recordsets for an entity in the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.
  2. Invalid entity name.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
Returns:
java.util.List - a List of Strings, one for each recordset
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
See Also:
getModelEntities()

getFieldMetaData

FieldMetaData getFieldMetaData(java.lang.String entityName,
                               java.lang.String recordSetName,
                               java.lang.String fieldName)
                               throws AppConnException,
                                      ApptrieveException

Gets metadata associated with a recordset field.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
recordSetName - java.lang.String - Name of the recordset of the entity in the Host Integrator model
fieldName - java.lang.String - Name of the field of the recordset in the Host Integrator model
Returns:
com.wrq.apptrieve.appconn.FieldMetaData - a metadata object for the specified field
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs

getFieldLocations

java.util.List getFieldLocations(java.util.List fieldNames)
                                 throws ApptrieveException

Gets a collection of ElementLocation objects for fields of the current record in the current recordset of the current entity. If fieldNames is null, getFieldLocations will return ElementLocation objects for all fields of the current record in the current recordset.

Field objects are always considered to be "linear". The ElementLocation object regionType will always be returned as REGION_TYPE_LINEAR.

This method is guaranteed to work correctly only when a record in the recordset is selected. If no record is selected:

Parameters:
fieldNames - java.util.List - List of field names to use in getting locations
Returns:
java.util.List - a List of ElementLocation objects, one for each field
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

getHomeEntityName

java.lang.String getHomeEntityName()
Gets the name of the home entity for the Host Integrator model.

Returns:
java.lang.String - The name of the home entity. For rejuvenation sessions employing models without entities, this method will return the string "<None>"

getModelEntities

java.util.List getModelEntities()
                                throws ApptrieveException
Gets the entity names of the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.

Returns:
java.util.List - a List of Strings, one for each entity in the model
Throws:
ApptrieveException - - if a Host Integrator server error occurs
See Also:
getCurrentEntity()

getModelVariableNames

java.util.List getModelVariableNames()
                                     throws ApptrieveException

Gets the names of all model variables in the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.

Returns:
java.util.List - a List of model variable names
Throws:
ApptrieveException - - if a Host Integrator server error occurs
See Also:
getModelVariables(), setModelVariables(java.util.Map)

getModelVariables

java.util.Map getModelVariables()
                                throws ApptrieveException

Gets the values of model variables in the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.

Returns:
java.util.Map - a Map of model variable name/value pairs
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setModelVariables(java.util.Map), getModelVariableNames()

getOperationMetaData

OperationMetaData getOperationMetaData(java.lang.String entityName,
                                       java.lang.String operationName)
                                       throws AppConnException,
                                              ApptrieveException

Gets metadata associated with an operation.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
operationName - java.lang.String - Name of the attribute of the entity in the Host Integrator model
Returns:
com.wrq.apptrieve.appconn.OperationMetaData - a metadata object for the specified operation
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs

getPatternLocations

java.util.List getPatternLocations(java.util.List patternNames)
                                   throws ApptrieveException

Gets a collection of ElementLocation objects for patterns of the current entity. If patternNames is null, getPatternLocations will return ElementLocation objects for all patterns of the entity.

Parameters:
patternNames - java.util.List - List of pattern names to use in getting locations
Returns:
java.util.List - a List of ElementLocation objects, one for each pattern
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

getRecordSetMetaData

RecordSetMetaData getRecordSetMetaData(java.lang.String entityName,
                                       java.lang.String recordSetName)
                                       throws AppConnException,
                                              ApptrieveException

Gets metadata associated with a recordset.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
recordSetName - java.lang.String - Name of the recordset of the entity in the Host Integrator model
Returns:
com.wrq.apptrieve.appconn.RecordSetMetaData - a metadata object for the specified recordset
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs

getRecordSetLocations

java.util.List getRecordSetLocations(java.util.List recordSetNames)
                                     throws ApptrieveException

Gets a collection of ElementLocation objects for recordSets of the current entity. If recordSetNames is null, getRecordSetLocations will return ElementLocation objects for all recordSets of the entity.

Parameters:
recordSetNames - java.util.List - List of recordset names to use in getting locations
Returns:
java.util.List - a List of ElementLocation objects, one for each recordset
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

getVariableMetaData

VariableMetaData getVariableMetaData(java.lang.String variableName)
                                     throws AppConnException,
                                            ApptrieveException

Gets metadata associated with a variable.

Parameters:
variableName - java.lang.String - Name of a variable in the Host Integrator model
Returns:
com.wrq.apptrieve.appconn.VariableMetaData - a metadata object for the specified model variable
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs

insertRecord

void insertRecord(java.util.Map record)
                  throws AppConnException,
                         ApptrieveException

Performs the insert operation for the current recordset.

Parameters:
record - java.util.Map - A map containing name-value pairs for the record elements to insert
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

insertRecords

void insertRecords(java.util.List records)
                   throws AppConnException,
                          ApptrieveException

Performs the insert operation for the current recordset multiple times.

This method sends the complete list of records to insert to the server at one time, making insertion of multiple records more efficient than the insertRecord method.

Parameters:
records - - a List of java.util.Map objects, one for record to insert into the entity. Each map object contains a set of name-value pairs for the record elements
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
insertRecord(java.util.Map)

moveCurrentRecordIndex

void moveCurrentRecordIndex(int movement)
                            throws ApptrieveException

Moves the current record index to a new position in the current recordset.

The movementCode can be one of the following AppConnModel fields:

Parameters:
movement - int - The type of movement to perform
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

nextRecord

AppConnModelRecord nextRecord(java.lang.String filterExpression)
                              throws ApptrieveException
Finds and return a record in the current recordset using a filter expression. See AppConnModel for filter expression syntax.

Searching starts with the record following the current record. If the current record is before the first record in the recordset, searching starts with the first record.

Parameters:
filterExpression - java.lang.String - An expression that qualifies the record to find. (null matches any record)
Returns:
AppConnModelRecord - the first record that matches the filterExpression. If no record matches the filterExpression, the method returns an AppConnModelRecord object that has no data values and has the index number set to -1.
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection

performEntityOperation

void performEntityOperation(java.lang.String operationName)
                            throws AppConnException,
                                   ApptrieveException

Performs an operation on the current entity.

Reasons for failure include:

  1. Server session has not been established.
  2. Invalid operation.

Parameters:
operationName - java.lang.String - The operation name
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setCurrentEntity(java.lang.String), getCurrentEntity(), getEntityOperations(java.lang.String)

selectCurrentRecord

void selectCurrentRecord()
                         throws ApptrieveException

Performs the selection operation for the current recordset.

Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
nextRecord(java.lang.String), setCurrentRecordIndex(int), selectRecordByFilter(java.lang.String), selectRecordByIndex(int)

selectRecordByFilter

boolean selectRecordByFilter(java.lang.String filterExpression)
                             throws ApptrieveException

Finds a record in the current recordset using a filter expression and perform its selection operation. See AppConnModel for filter expression syntax.

Searching starts with the record following the current record. If the current record is before the first record in the recordset, searching starts with the first record.

Parameters:
filterExpression - java.lang.String - An expression that qualifies the record to find. (null matches any record)
Returns:
boolean - true if the selection succeeds, false if the method fails to find a record to select
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
selectCurrentRecord(), selectRecordByIndex(int)

selectRecordByIndex

boolean selectRecordByIndex(int index)
                            throws ApptrieveException

Performs its selection operation on a record in the current recordset. The record to select is selected by the provided index number.

Parameters:
index - int - The index of the record to select
Returns:
boolean - true if the selection succeeds, false if a record is not found to select
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
selectCurrentRecord(), selectRecordByFilter(java.lang.String)

setAttributes

void setAttributes(java.util.Map attributes)
                   throws ApptrieveException
Sets the attributes in the current entity. The map will contain attributes (name/value pairs) that are to be inserted in the entity.

The map does not need to contain all of the attributes for the entity, but should contain all of the required attributes for the entity.

Parameters:
attributes - java.util.Map - A map containing attributes (name/value pairs)
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setAttributesDelayed(java.util.Map, java.lang.String), getAttributes(java.util.List)

setAttributesDelayed

void setAttributesDelayed(java.util.Map attributes,
                          java.lang.String entityName)
                          throws AppConnException,
                                 ApptrieveException

Sets the attributes of an entity.

The map contains attributes (name/value pairs) that are to be set in the entity. The map does not need to contain all of the attributes for the entity, but should contain all of the required attributes for the entity. If the entity is not specified then the current entity is used.

Parameters:
attributes - java.util.Map - A map containing attributes (name/value pairs)
entityName - java.lang.String - Name of the entity in the Host Integrator model
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
setCurrentEntity(java.lang.String), getCurrentEntity(), fetchRecords(int, java.util.List, java.lang.String), setAttributes(java.util.Map)

setCurrentEntity

void setCurrentEntity(java.lang.String entityName)
                      throws AppConnException,
                             ApptrieveException

Sets the current entity.

The legacy application will traverse to the screen that corresponds to that entity.

Reasons for failure include:

  1. Server session has not been established.
  2. Invalid entity name.
  3. No traversal path to entity.

Parameters:
entityName - java.lang.String - Name of the entity in the Host Integrator model
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
getCurrentEntity()

setCurrentRecordIndex

boolean setCurrentRecordIndex(int index)
                              throws ApptrieveException

Changes the index number of the current record in the current recordset.

To force the current record to be the current host record, use the AppConnModel field SyncToHost, which has a value of -1, as the index parameter.

Parameters:
index - int - The index of the record to make current
Returns:
boolean - true if the current record was changed to the corresponding to index, false if not
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
getCurrentRecordIndex(), getCurrentRecord()

setCurrentRecordSetByName

void setCurrentRecordSetByName(java.lang.String recordSetName)
                               throws AppConnException,
                                      ApptrieveException

Sets the current recordset by name.

Parameters:
recordSetName - java.lang.String - The name of the recordset to make current
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
getCurrentRecordSetName()

setModelVariables

void setModelVariables(java.util.Map variables)
                       throws ApptrieveException

Sets the values of variables in the Host Integrator model.

Reasons for failure include:

  1. Server session has not been established.
  2. Invalid variable name.

Parameters:
variables - java.util.Map - A collection of name/value pairs for the variables
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
getModelVariables(), getModelVariableNames()

updateCurrentRecord

void updateCurrentRecord(java.util.Map record)
                         throws AppConnException,
                                ApptrieveException

Changes the values of the current record in the current recordset.

Parameters:
record - java.util.Map - A map containing name-value pairs for the record elements to change
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
updateRecordByFilter(java.util.Map, java.lang.String), updateRecordByIndex(java.util.Map, int), updateRecords(java.util.Map, java.lang.String)

updateRecordByFilter

boolean updateRecordByFilter(java.util.Map record,
                             java.lang.String filterExpression)
                             throws AppConnException,
                                    ApptrieveException

Changes the values of a record in the current recordset. The record to change is the first one after the current record that satisfies the filter expression. See AppConnModel for filter expression syntax.

Parameters:
record - java.util.Map - A map containing name-value pairs for the record elements to change
filterExpression - java.lang.String - An expression that qualifies the record to update. (null matches any record)
Returns:
boolean - true if a record was found to update and the Host Integrator server performed the record update, otherwise false
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
updateCurrentRecord(java.util.Map), updateRecordByIndex(java.util.Map, int), updateRecords(java.util.Map, java.lang.String)

updateRecordByIndex

boolean updateRecordByIndex(java.util.Map record,
                            int index)
                            throws AppConnException,
                                   ApptrieveException

Changes the values of a record in the current recordset. The record to change is selected by the provided index number.

Parameters:
record - java.util.Map - A map containing name-value pairs for the record elements to change
index - int - The index of the record to update
Returns:
boolean - true if the Host Integrator server performed the record update, false otherwise
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
updateCurrentRecord(java.util.Map), updateRecordByFilter(java.util.Map, java.lang.String), updateRecords(java.util.Map, java.lang.String)

updateRecords

int updateRecords(java.util.Map record,
                  java.lang.String filterExpression)
                  throws AppConnException,
                         ApptrieveException

Changes the values of records in the current recordset.

The records to change those after the current record that satisfy the filter expression. All same set of changes are applied to all records that satisfy the filterExpression. See AppConnModel for filter expression syntax.

To apply changes to all records in a recordset that match the filter, the current record must be before the first record of the recordset. This is the case upon navigating to the model entity that contains the recordset. If other methods have be executed that change the current record index, reposition to before the first record using setCurrentRecordIndex(), moveCurrentRecordIndex() or by navigating away from the current entity and then back again.

Parameters:
record - java.util.Map - A map containing name-value pairs for the record elements to change
filterExpression - java.lang.String - An expression that qualifies the records to update. (null matches all records)
Returns:
int - the number of records for which the Host Integrator server performed a record update.
Throws:
AppConnException - - if there is a parameter error
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
updateCurrentRecord(java.util.Map), updateRecordByFilter(java.util.Map, java.lang.String), updateRecordByIndex(java.util.Map, int)

waitForEntityChange

void waitForEntityChange(java.lang.String entityName,
                         int timeout)
                         throws ApptrieveException
Deprecated. Use of this method should be avoided, because it can sometimes result in a race condition.

Waits for the recognition of a new entity that is not 'entityName'.

If entityName is null or empty, the method returns upon recognition of any new entity. Exception occurs if timeout period elapses before the Host Integrator Server recognizes a new entity.

Parameters:
entityName - java.lang.String - the name of the entity that cannot satisfy the entity change condition, typically the entity that was current when the method is called.
timeout - int - the timeout period in seconds
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
AppConnTerm.performAidKey(int)

waitForCondition

void waitForCondition(int timeout,
                      java.lang.String expression,
                      java.lang.String entityName)
                      throws ApptrieveException

Waits for an expression to become true for an entity on the Host Integrator server.

If the expression is empty or null, this method waits until the Host Integrator server has recognized the entity specified in the entityName parameter. If the entityName parameter is empty or null, the method waits until the expression is true for the current entity. An exception occurs if timeout period elapses before the expression becomes true.

Parameters:
timeout - int - the timeout period in seconds
expression - java.lang.String - the expression to wait for
entityName - java.lang.String - the name of the entity to use as the context for the expression.
Throws:
ApptrieveException - - if a Host Integrator server error occurs
MetaDataOnlyException - - if this is a metadata-only connection
See Also:
AppConnTerm.performAidKey(int)

processString

java.lang.String processString(java.lang.String inStr)
                               throws ApptrieveException

Calls the ProcessString event handler on the server.

Parameters:
inStr - - String input to the ProcessString event
Returns:
String - the processed String
Throws:
ApptrieveException - - if a Host Integrator server error occurs