com.unvired.database

Interface IDataStructure

All Known Implementing Classes:

com.unvired.model.DataStructure, InfoMessage

public interface IDataStructure

IDataStructure represents application data as a business object.

• Unvired data model consists of a set of Business Entities.
• Business Entity is a logical construct consisting of a header item and other children items (Note: Terms Structure and Item are used interchangeably). Business Entity can have only one Header and many children Items.
• Header / Item is a collection of Fields.
• Field is a field name and value pair.

A sample data model is provided below:

 
 <Application name="CRM" description="CRM Mobile App" version="1.0" dbversion="1.0" package="com.mycompany.crm" namespace="mycompany">
 		<BusinessEntity name="CUSTOMER" description="Customer">
 			<header className="com.unvired.template.saperp.so.be.CUSTOMER" description="" name="CUSTOMER_HEADER">
 				<Field name="CUSTOMER_NO" description="Customer No" sqlType="TEXT" isGid="true" length="10" mandatory="true" />
 				<Field name="CUSTOMER_NAME" description="Customer Name" sqlType="TEXT" length="12" mandatory="true" />
 				<Field name="STREET" description="Street" sqlType="TEXT" length="50" mandatory="false" />
 				<Field name="CITY" description="City" sqlType="TEXT" length="50" mandatory="false" />
 				<Field name="PIN_CODE" description="Pin Code" sqlType="TEXT" length="10" mandatory="false" />
 			</header>
 			<item className="com.unvired.template.saperp.so.be.CUSTOMER_CONTACT" description="" name="CUSTOMER_CONTACT">
 				<Field name="CUSTOMER_NO" description="Customer No" sqlType="TEXT" isGid="true" length="10" mandatory="true" />
 				<Field name="CONTACT_NO" description="Contact No" sqlType="TEXT" isGid="true" length="12" mandatory="true" />
 				<Field name="CONTACT_NAME" description="Contact Name" sqlType="TEXT" length="50" mandatory="false" />
 				<Field name="TEL_NO" description="Telephone No" sqlType="TEXT" length="10" mandatory="false" />
 			</item>
 		</BusinessEntity>
 	</Application>

 

Overview

All headers and items in the Business Entity are represented as IDataStructure. The headers and items of the business entities extend DataStructure. DataStructure is the default implementation of IDataStructure.

When headers and items are fetched from the database the objects are of type IDataStructure.

The following topics about the IDataStructure are covered here:

1. Keys
2. Fields
3. Status
4. Relationships
5. Database Operations
6. Info Messages
7. Generation

Generation

Application data model is created using the Unvired Designer Tool. Unvired Designer is a plugin to Eclipse used to model the application. Once the application is modelled the business objects can be generated. The business entities modelled are generated as Java objects. The headers and items are generated as separate Java objects.

If required the Java objects can also be handwritten. All data model objects have to extend DataStructure.

Keys

IDataStructure recognizes data uniquely in 2 ways.

• LID - Local identifier. A local identifier is a technical key that uniquely identifies each data structure object uniquely. LID is represented by the field FIELD_LID. Each data structure object contains a field called LID and LID is like the primary key for the data structure.
• GID - Global Identifier. A global identifier is a business key that uniquely identifies each data structure object uniquely. GID can be a single field or a set of fields. One of more fields are marked as GID fields in the data model. For a particular type of data structure all data structure rows should have unique GID fields. GID fields are similar to a composite primary key.

Fields that form the GID can be obtained using getGidFieldNames(). GID fields' values can be obtained using getGids().

Header and Item Relationship

Header and item are related through the FIELD_FID. FIELD_FID of the item should have the FIELD_LID value of the header. FIELD_FID of the header is empty. While inserting business objects to the database the FIELD_FID of the item has to be explicitly set with the FIELD_LID of the header.

Foreign Key Relationships

Apart from the header and item relationship via FIELD_FID no other foreign key relationship is supported in the data model. Other related data structures have to be logical relationships.

Database Operations

Database operations on the data structure objects are achieved via IDataManager.

Statuses

Data structure objects (both header and item) have statuses representing their current states. 'Object Status' field at the BE level is used to indicate data action (GLOBAL, ADD, MODIFY or DELETE) and 'Sync Status' field at the BE level is used to indicate synchronization state (OUTBOX, SENT_ITEMS or ERRORS).

 OBJECT_STATUS: Object status indicates the state of the data. OBJECT_STATUS is available at both the header and item level.
        i.  GLOBAL � Data sent from the server
        ii. ADD � Data added on the mobile device
        iii.MODIFY � Data modified on the mobile device
        iv. DELETE � Data marked for deletion on the mobile device
 

 SYNC_STATUS: Sync status indicates the state of the data exchange. SYNC_STATUS is available at both the header and item level.
        i.  NONE � No status associated, by default there is no value for the SYNS_STATUS field
        ii. QUEUED � Queued in the outbox to be sent to the server
        iii.SENT � Sent to the server and waiting for a response
        iv. ERROR � Response obtained from the server and has resulted in an error
 

InfoMessages

All errors and warnings associated with the data structure during a synchronization with the server are stored as InfoMessage. InfoMessages related to a data structure can be obtained using getInfoMessages().

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	IDataStructure.OBJECT_STATUS
static class	IDataStructure.SYNC_STATUS

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	FIELD_FID
static java.lang.String	FIELD_HAS_CONFLICT
static java.lang.String	FIELD_LID
static java.lang.String	FIELD_OBJECT_STATUS
static java.lang.String	FIELD_SYNC_STATUS
static java.lang.String	FIELD_TIMESTAMP
static java.lang.String	FIELD_TYPE_FID
static java.lang.String	FIELD_TYPE_HAS_CONFLICT
static java.lang.String	FIELD_TYPE_LID
static java.lang.String	FIELD_TYPE_OBJECT_STATUS
static java.lang.String	FIELD_TYPE_SYNC_STATUS
static java.lang.String	FIELD_TYPE_TIMESTAMP

Method Summary

Modifier and Type	Method and Description
java.lang.String	getBEName() Gets the business entity name to which the structure belongs to.
java.lang.String[]	getChildrenTableNames() Gets the names of all the children structures (items) of the header.
java.lang.String	getFid() Gets the FID of the data structure.
java.lang.Object	getField(java.lang.String fieldName) Gets the value associated with the field fieldName.
int	getFieldCount() Gets the number of fields in the data structure.
java.util.Enumeration<java.lang.String>	getFieldNames() Gets the names of the field that are part of the data structure.
java.lang.String	getFieldType(java.lang.String fieldName) Gets the data type of the field.
java.lang.String[]	getGidFieldNames() Gets the names of the fields that are designated as GID (global identifier) fields.
java.lang.Object[]	getGids() Gets the values associated with the GID (global identifier) fields.
boolean	getHasConflict() Get for the data structure has conflicted or not
InfoMessage[]	getInfoMessages() Gets the info messages associated with the data structure.
java.lang.String	getLid() Gets the lid of the data structure.
IDataStructure.OBJECT_STATUS	getObjectStatus() Gets the object status of the data structure.
IDataStructure.SYNC_STATUS	getSyncStatus() Gets the sync status of the data structure.
java.lang.String	getTableName() Gets the data structure name.
java.lang.Long	getTimeStamp() Gets the time stamp of the last modification of the data structure.
boolean	isHeader() Checks if the data structure is a header.
boolean	isModified()
void	setFid(java.lang.String fid) Sets the fid of the data structure.
boolean	setField(java.lang.String fieldName, java.lang.Object value) Sets the value for the given field.
boolean	setFieldBasedOnDataType(java.lang.String fieldName, java.lang.Object value)
void	setHasConflict(boolean hasConflict) Set for the data structure for conflict
void	setLid(java.lang.String lid) Sets the lid of the data structure
void	setModifiedFlag(boolean modifiedFlag)
void	setObjectStatus(IDataStructure.OBJECT_STATUS objectStatus) Sets the objectStatus of the data structure
void	setSyncStatus(IDataStructure.SYNC_STATUS syncStatus) Sets the syncStatus of the data structure
void	setTimeStamp(java.lang.Long timeStamp) Sets the time stamp of last modification of the data structure in milliseconds since January 1, 1970 00:00:00 UTC.

Field Detail

FIELD_LID

static final java.lang.String FIELD_LID

See Also:

Constant Field Values

FIELD_FID

static final java.lang.String FIELD_FID

See Also:

Constant Field Values

FIELD_TIMESTAMP

static final java.lang.String FIELD_TIMESTAMP

See Also:

Constant Field Values

FIELD_OBJECT_STATUS

static final java.lang.String FIELD_OBJECT_STATUS

See Also:

Constant Field Values

FIELD_SYNC_STATUS

static final java.lang.String FIELD_SYNC_STATUS

See Also:

Constant Field Values

FIELD_HAS_CONFLICT

static final java.lang.String FIELD_HAS_CONFLICT

See Also:

Constant Field Values

FIELD_TYPE_LID

static final java.lang.String FIELD_TYPE_LID

See Also:

Constant Field Values

FIELD_TYPE_FID

static final java.lang.String FIELD_TYPE_FID

See Also:

Constant Field Values

FIELD_TYPE_TIMESTAMP

static final java.lang.String FIELD_TYPE_TIMESTAMP

See Also:

Constant Field Values

FIELD_TYPE_OBJECT_STATUS

static final java.lang.String FIELD_TYPE_OBJECT_STATUS

See Also:

Constant Field Values

FIELD_TYPE_SYNC_STATUS

static final java.lang.String FIELD_TYPE_SYNC_STATUS

See Also:

Constant Field Values

FIELD_TYPE_HAS_CONFLICT

static final java.lang.String FIELD_TYPE_HAS_CONFLICT

See Also:

Constant Field Values

Method Detail

getBEName

java.lang.String getBEName()

Gets the business entity name to which the structure belongs to.

Returns:

Returns the business entity name.

getTableName

java.lang.String getTableName()

Gets the data structure name. The sturcture's name is also the name of the table in the database.

Returns:

Returns the data structure / table name.

isHeader

boolean isHeader()

Checks if the data structure is a header.

Returns:

Returns True, if the data structure is a header. Otherwise false.

getLid

java.lang.String getLid()

Gets the lid of the data structure.

Returns:

Returns the Lid of the data structure.

setLid

void setLid(java.lang.String lid)

Sets the lid of the data structure

Parameters:

lid - Lid value of the data structure.

getFid

java.lang.String getFid()

Gets the FID of the data structure. Header and item are related through the FIELD_FID. FIELD_FID of the item should have the FIELD_LID value of the header. FIELD_FID of the header is empty. While inserting business objects to the database the FIELD_FID of the item has to be explicitly set with the FIELD_LID of the header.

Returns:

Return the fid. Fid of the header is empty.

setFid

void setFid(java.lang.String fid)

Sets the fid of the data structure. Header and item are related through the FIELD_FID. FIELD_FID of the item should have the FIELD_LID value of the header. FIELD_FID of the header is empty. While inserting business objects to the database the FIELD_FID of the item has to be explicitly set with the FIELD_LID of the header.

Parameters:

fid - Lid of the header has to be set as the fid in the item data structure. Fid should no be set for headers.

getTimeStamp

java.lang.Long getTimeStamp()

Gets the time stamp of the last modification of the data structure.

Returns:

Return the time stamp in milliseconds since January 1, 1970 00:00:00 UTC.

setTimeStamp

void setTimeStamp(java.lang.Long timeStamp)

Sets the time stamp of last modification of the data structure in milliseconds since January 1, 1970 00:00:00 UTC.

Parameters:

timeStamp - Timestamp of last modification of the data structure in milliseconds since January 1, 1970 00:00:00 UTC.

setField

boolean setField(java.lang.String fieldName,
                 java.lang.Object value)

Sets the value for the given field.

Parameters:

fieldName - Field name that has to be set with the given value.

value - Value to be set to for the field.

Returns:

Returns true, if setting the value to the field is successful.

setFieldBasedOnDataType

boolean setFieldBasedOnDataType(java.lang.String fieldName,
                                java.lang.Object value)
                         throws MissingFieldException,
                                MissingFieldTypeException

Throws:

MissingFieldException

MissingFieldTypeException

getField

java.lang.Object getField(java.lang.String fieldName)

Gets the value associated with the field fieldName.

Parameters:

fieldName - Name of the field whose value is required.

Returns:

Returns the value associated with the field.

getFieldType

java.lang.String getFieldType(java.lang.String fieldName)

Gets the data type of the field. Supported data types are available in DataTypes.

Parameters:

fieldName - Name of the field whose data type is required.

Returns:

Returns the data type of the field.

getFieldCount

int getFieldCount()

Gets the number of fields in the data structure.

Returns:

Returns the field count.

getFieldNames

java.util.Enumeration<java.lang.String> getFieldNames()

Gets the names of the field that are part of the data structure.

Returns:

Returns an enumeration of field names.

getGidFieldNames

java.lang.String[] getGidFieldNames()

Gets the names of the fields that are designated as GID (global identifier) fields.

Returns:

Returns an array of field names that are marked as GIDs.

getGids

java.lang.Object[] getGids()
                    throws DBException

Gets the values associated with the GID (global identifier) fields.

Returns:

Returns the values associated with the GID fields.

Throws:

DBException - Throws a DBException when the values cannot be fetched from the database.

isModified

boolean isModified()

setModifiedFlag

void setModifiedFlag(boolean modifiedFlag)

getChildrenTableNames

java.lang.String[] getChildrenTableNames()
                                  throws DBException

Gets the names of all the children structures (items) of the header. This method is only applicable for header data structures.

Returns:

Returns the children structure names

Throws:

DBException - Throws a DBException when the values cannot be fetched from the database.

getObjectStatus

IDataStructure.OBJECT_STATUS getObjectStatus()

Gets the object status of the data structure.

Returns:

Returns the Object Status of the data structure.

setObjectStatus

void setObjectStatus(IDataStructure.OBJECT_STATUS objectStatus)

Sets the objectStatus of the data structure

Parameters:

objectStatus - Object status indicates the state of the data.

getSyncStatus

IDataStructure.SYNC_STATUS getSyncStatus()

Gets the sync status of the data structure.

Returns:

Returns the Sync Status of the data structure.

setSyncStatus

void setSyncStatus(IDataStructure.SYNC_STATUS syncStatus)

Sets the syncStatus of the data structure

Parameters:

syncStatus - Sync status indicates the state of the data exchange.

getHasConflict

boolean getHasConflict()

Get for the data structure has conflicted or not

setHasConflict

void setHasConflict(boolean hasConflict)

Set for the data structure for conflict

Parameters:

hasConflict - mark data structure as conflicted

getInfoMessages

InfoMessage[] getInfoMessages()
                       throws DBException

Gets the info messages associated with the data structure. All errors and warnings associated with the data structure during a synchronization with the server are stored as InfoMessage.

Returns:

InfoMessage associated with the data structure.

Throws:

DBException - Throws a DBException when the values cannot be fetched from the database.