org.asam.ods

Interface ApplicationAttributeOperations

All Known Subinterfaces:

ApplicationAttribute

All Known Implementing Classes:

_ApplicationAttributeStub, ApplicationAttribute, ApplicationAttribute, ApplicationAttributePOA

public interface ApplicationAttributeOperations

The ASAM ODS application attribute interface.

Method Summary

Methods

Modifier and Type	Method and Description
ApplicationElement	getApplicationElement() (4017) Return the application element to which the attribute belongs.
BaseAttribute	getBaseAttribute() (4001) Get the base attribute of the application attribute.
DataType	getDataType() (4002) Get the data type of the application attribute.
EnumerationDefinition	getEnumerationDefinition() (4020) Get the definition of the enumeration.
int	getLength() (4003) Get the maximum allowed string length of the value of the application attribute.
java.lang.String	getName() (4004) Get the name of the application attribute.
ACL[]	getRights() (4016) Retrieve access control list information of the given object.
T_LONGLONG	getUnit() (4005) Get the unit Id of the application attribute.
boolean	hasUnit() (4022) Has the attribute an unit.
boolean	hasValueFlag() (4024) Deprecated, not used any more since ASAM ODS 5.2.
boolean	isAutogenerated() (4018) Get the auto generate flag of the application attribute.
boolean	isObligatory() (4006) Get the obligatory flag of the application attribute.
boolean	isUnique() (4007) Get the unique flag of the application attribute.
void	setBaseAttribute(BaseAttribute baseAttr) (4008) Set the base attribute of the application attribute.
void	setDataType(DataType aaDataType) (4009) Set the data type of the application attribute.
void	setEnumerationDefinition(EnumerationDefinition enumDef) (4021) Set the definition of the enumeration.
void	setIsAutogenerated(boolean isAutogenerated) (4019) Set the auto generate flag of the application attribute.
void	setIsObligatory(boolean aaIsObligatory) (4010) Set the obligatory flag of the application attribute.
void	setIsUnique(boolean aaIsUnique) (4011) Set the unique flag of the application attribute.
void	setLength(int aaLength) (4012) Set the maximum allowed length of the application attribute.
void	setName(java.lang.String aaName) (4013) Set the name of an application attribute.
void	setRights(InstanceElement usergroup, int rights, RightsSet set) (4015) The given user group the rights should be set for.
void	setUnit(T_LONGLONG aaUnit) (4014) Set the unit Id of an application attribute.
void	withUnit(boolean withUnit) (4023) Specifies whether the attribute will have an unit or not.
void	withValueFlag(boolean withValueFlag) (4025) Deprecated, not used any more since ASAM ODS 5.2.

Method Detail

getBaseAttribute

BaseAttribute getBaseAttribute()
                               throws AoException

(4001) Get the base attribute of the application attribute.

Returns:

The base attribute of the application attribute. A 'null' is returned if the application attribute has no base attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getDataType

DataType getDataType()
                     throws AoException

(4002) Get the data type of the application attribute.

Returns:

The data type of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getLength

int getLength()
              throws AoException

(4003) Get the maximum allowed string length of the value of the application attribute.

Returns:

The maximum allowed string length of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getName

java.lang.String getName()
                         throws AoException

(4004) Get the name of the application attribute.

Returns:

The name of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getUnit

T_LONGLONG getUnit()
                   throws AoException

(4005) Get the unit Id of the application attribute. The unit Id is only valid for the current server.

Returns:

The unit Id of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

isObligatory

boolean isObligatory()
                     throws AoException

(4006) Get the obligatory flag of the application attribute.

Returns:

The obligatory flag of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

isUnique

boolean isUnique()
                 throws AoException

(4007) Get the unique flag of the application attribute. This method can be used to check whether the attributes values of the instances must have unique values.

Returns:

The unique flag of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setBaseAttribute

void setBaseAttribute(BaseAttribute baseAttr)
                      throws AoException

(4008) Set the base attribute of the application attribute. This allows the client to declare the application attribute (new or existing) additional to a base attribute. The application attribute will become the derived attribute of the given base attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. The base attribute must be unique within the application element otherwise the exception AO_DUPLICATE_BASE_ATTRIBUTE is thrown. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. If this method is called before the first commit it will not throw the following exceptions: AO_INVALID_DATATYPE AO_MISSING_VALUE AO_NOT_UNIQUE. After the first commit, there may be instances of the application attribute. These instances may cause the following problems: AO_INVALID_DATATYPE: The data type of the base attribute is not the same as the data type of the instantiated attributes. AO_MISSING_VALUE: The obligatory flag of the base attribute is set but there are one or more empty values in the instances. AO_NOT_UNIQUE: The unique flag of the base attribute is set but the values of the instances are not unique. The length, the name and the unit of the application attribute are not affected by this call.

Parameters:

baseAttr - The base attribute.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_DUPLICATE_BASE_ATTRIBUTE AO_IMPLEMENTATION_PROBLEM AO_INVALID_DATATYPE AO_MISSING_VALUE AO_NOT_IMPLEMENTED AO_NOT_UNIQUE AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setDataType

void setDataType(DataType aaDataType)
                 throws AoException

(4009) Set the data type of the application attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. It is not allowed to set the data type of application attributes that represent base attributes. An attempt to set the data type of such an application attribute will result in the exception AO_IS_BASE_ATTRIBUTE. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. If this method is called before the first commit it will not throw the following exception: AO_INVALID_DATATYPE After the first commit, there may be instances of the application attribute. These instances may cause the following problem: AO_INVALID_DATATYPE: The data type of the base attribute is not the same as the data type of the instantiated attributes.

Parameters:

aaDataType - The data type.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_HAS_BASE_ATTRIBUTE AO_IMPLEMENTATION_PROBLEM AO_INVALID_DATATYPE AO_IS_BASE_ATTRIBUTE AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setIsObligatory

void setIsObligatory(boolean aaIsObligatory)
                     throws AoException

(4010) Set the obligatory flag of the application attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. It is not allowed to set the obligatory flag of application attributes that represent base attributes. An attempt to set the obligatory flag of such an application attribute will result in the exception AO_IS_BASE_ATTRIBUTE. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. If this method is called before the first commit it will not throw the following exception: AO_MISSING_VALUE After the first commit, there may be instances of the application attribute. These instances may cause the following problem: AO_MISSING_VALUE: The obligatory flag of the base attribute is set but there are one or more empty values in the instances.

Parameters:

aaIsObligatory - The obligatory flag.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_HAS_BASE_ATTRIBUTE AO_IMPLEMENTATION_PROBLEM AO_IS_BASE_ATTRIBUTE AO_MISSING_VALUE AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setIsUnique

void setIsUnique(boolean aaIsUnique)
                 throws AoException

(4011) Set the unique flag of the application attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. The server will check if the values of the instance attributes are unique. If this flag is set and the values of an attribute are not unique when using the method setValue an exception is thrown. If instances of the application element already exist that contain non-unique values and the flag shall be set this method throws an exception. It is not allowed to set the unique flag of application attributes that represent base attributes. An attempt to set the unique flag of such an application attribute will result in the exception AO_IS_BASE_ATTRIBUTE. If the unique flag is set to TRUE the obligatory flag is also set to TRUE. The previous values of both flags do not matter in this case. Setting the unique flag to FALSE does not affect the obligatory flag. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. If this method is called before the first commit it will not throw the following exception: AO_MISSING_VALUE AO_NOT_UNIQUE After the first commit, there may be instances of the application attribute. These instances may cause the following problem: AO_MISSING_VALUE: The obligatory flag of the base attribute is set but there are one or more empty values in the instances. AO_NOT_UNIQUE: The unique flag of the base attribute is set but the values of the instances are not unique.

Parameters:

aaIsUnique - The unique flag.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_HAS_BASE_ATTRIBUTE AO_IMPLEMENTATION_PROBLEM AO_IS_BASE_ATTRIBUTE AO_MISSING_VALUE AO_NOT_IMPLEMENTED AO_NOT_UNIQUE AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setLength

void setLength(int aaLength)
               throws AoException

(4012) Set the maximum allowed length of the application attribute. The maximum value accepted by the ASAM ODS server for this length information depends on the underlying physical storage. For the physical storage specified in chapter 3 the maximum allowed length will be stored in the AFLEN value in SVCATTR, and it is restricted by the maximum length of string type database fields. If a length is specified that exceeds the capabilities of the underlying physical storage the server will throw the exception AO_INVALID_LENGTH. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. This method is useful for ODS database design tools. Negative length values are not allowed. This method provides only a hint to a database server in the design phase which size the data entries may have. The length is only relevant for attribute values with the data type DT_STRING, DS_STRING, DT_DATE, DS_DATE, all components of DT_EXTERNALREFERENCE and of DS_EXTERNALREFERENCE, and the header portion of DT_BLOB. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. If this method is called before the first commit it will not throw the following exception: AO_HAS_INSTANCES After the first commit, there may be instances of the application attribute. These instances may cause the exception AO_HAS_INSTANCES if the instances of the application attribute are not empty.

Parameters:

aaLength - The maximum attribute length.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_HAS_INSTANCES AO_IMPLEMENTATION_PROBLEM AO_INVALID_LENGTH AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setName

void setName(java.lang.String aaName)
             throws AoException

(4013) Set the name of an application attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. The name must be unique. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. The name of an application attribute must not exceed the maximum name length of the underlying physical storage. Current server implementations typically restrict it to 30 characters.

Parameters:

aaName - The application attribute name.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_DUPLICATE_NAME AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setUnit

void setUnit(T_LONGLONG aaUnit)
             throws AoException

(4014) Set the unit Id of an application attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. The unit Id is only valid for the current server. If instances of the application attribute exist, the respective values are automatically converted to the new unit. If there is no known conversion an exception is thrown. The automatic conversion can be avoided if the unit is set to zero. After that the transaction must be committed. In the next step the new unit may be set in another transaction. The automatic conversion is done only for the following data types: DT_BYTE DT_COMPLEX DT_DCOMPLEX DT_DOUBLE DT_FLOAT DT_LONG DT_LONGLONG DT_SHORT as well as for the corresponding sequence data types. For complex data types the real and imaginary part are converted separately. If the unit of an attribute is set the unit is constant. If the value of the attribute has another unit the value is recalculated to the unit of the application attribute. If there is no unit associated with the application attribute the unit at the attribute value is stored and reported on request at the instance. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time. If this method is called before the first commit it will not throw the following exceptions: AO_INCOMPATIBLE_UNITS AO_MATH_ERROR After the first commit, there may be instances of the application attribute. These instances may cause the following problems: AO_INCOMPATIBLE_UNITS: No conversion rules is known to convert the unit. AO_MATH_ERROR: Converting the values to the new unit results in data overflow or underflow or a division by zero is detected.

Parameters:

aaUnit - The unit Id.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_INCOMPATIBLE_UNITS AO_MATH_ERROR AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_UNKNOWN_UNIT

setRights

void setRights(InstanceElement usergroup,
             int rights,
             RightsSet set)
               throws AoException

(4015) The given user group the rights should be set for. defines the rights to set or to clear. If the parameter is set to 'set', the rights in are set all others are cleared. If the parameter is set to 'add', the rights in are added to the existing rights. If the parameter is set to 'remove', the rights in are removed from the existing rights.

Parameters:

usergroup - The user group for which the rights will be modified.

rights - The new right for the user group. The rights constants are defined in the interface SecurityRights. The interface definition language IDL does not allow to set the values of enumerations thus the constant definitions had to be done in an interface.

set - What to do with the new right.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_TRANSACTION_NOT_ACTIVE

getRights

ACL[] getRights()
                throws AoException

(4016) Retrieve access control list information of the given object.

Returns:

The access control list entries of the given application attribute.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getApplicationElement

ApplicationElement getApplicationElement()
                                         throws AoException

(4017) Return the application element to which the attribute belongs.

Returns:

The application element of the attribute.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

isAutogenerated

boolean isAutogenerated()
                        throws AoException

(4018) Get the auto generate flag of the application attribute.

Returns:

The auto generate flag of the application attribute.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

setIsAutogenerated

void setIsAutogenerated(boolean isAutogenerated)
                        throws AoException

(4019) Set the auto generate flag of the application attribute. It is allowed to modify the application attribute outside a transaction but it is recommended to activate a transaction. For performance and flexibility reasons this set-method should be used before the new application attribute is committed the first time.

Parameters:

isAutogenerated - The auto generate flag.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_HAS_BASE_ATTRIBUTE AO_IMPLEMENTATION_PROBLEM AO_IS_BASE_ATTRIBUTE AO_MISSING_VALUE AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

getEnumerationDefinition

EnumerationDefinition getEnumerationDefinition()
                                               throws AoException

(4020) Get the definition of the enumeration.

Returns:

The ASAM ODS enumeration.

Throws:

AoException - with the following possible error codes: AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_INVALID_DATATYPE

setEnumerationDefinition

void setEnumerationDefinition(EnumerationDefinition enumDef)
                              throws AoException

(4021) Set the definition of the enumeration. This method modifies the application model, only the super user can use this method. The AoException AO_INVALID_DATATYPE is thrown when the data type of the attribute is not DT_ENUM.

Parameters:

enumDef - The new enumeration definition.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_TRANSACTION_NOT_ACTIVE AO_ACCESS_DENIED AO_INVALID_DATATYPE

hasUnit

boolean hasUnit()
                throws AoException

(4022) Has the attribute an unit. If this flag is set, all the attributes of the instances derived from this attribute will has an unit.

Returns:

The flag if the attribute has an unit.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

withUnit

void withUnit(boolean withUnit)
              throws AoException

(4023) Specifies whether the attribute will have an unit or not. A call to the method setUnit() will automatically set the withUnit flag to TRUE.

Parameters:

withUnit - TRUE, if the attribute will have an unit, FALSE otherwise.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_TRANSACTION_NOT_ACTIVE

hasValueFlag

boolean hasValueFlag()
                     throws AoException

(4024) Deprecated, not used any more since ASAM ODS 5.2. Has the attribute a value flag? If this flag is set, all the attributes of the instances derived from this attribute will have a value flag. If this flag is not set the flag in the TS_Value structure can be ignored.

Returns:

TRUE if the attribute has a value flag, selse FALSE.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE

withValueFlag

void withValueFlag(boolean withValueFlag)
                   throws AoException

(4025) Deprecated, not used any more since ASAM ODS 5.2. Specifies whether the attribute has a value flag or not. If this flag isn't set the flag of the TS_Value will be ignored by the server.

Parameters:

withValueFlag - TRUE flag if the attribute becomes a value flag, else FALSE.

Throws:

AoException - with the following possible error codes: AO_BAD_PARAMETER AO_CONNECTION_LOST AO_IMPLEMENTATION_PROBLEM AO_NOT_IMPLEMENTED AO_NO_MEMORY AO_SESSION_NOT_ACTIVE AO_TRANSACTION_NOT_ACTIVE