Data Connector API

The Data Connector receives data read, write and delete requests from the device via the Host and implements them as required.

Data Connector Flow

There are 3 distinct phases during processing of a synchronization rule:

Phase 1:

The device sends any changed records and data records deleted by the user.

updateRecords();

The function returns either null if no changes are required on the device, or a table containing records that should be changed or updated on the device as a result of the query. For example, if data records on the device are normally removed from the device once the datasource has been updated, this can be used to keep records on the device that could not be updated, and in addition, data such as a status field could be changed to notify the user.

Any records not returned in the Maptable returned object can optionally be removed from the device (project configuration).

Phase 2:

The device sends a request for new records, which calls getRecords() and optionally can send a list of the primary keys of records it currently has (to aid in creating the correct list of records to return). The Data Connector returns the new records requested and the primary keys of any records that should be removed from the device.

Querydata is populated from data on a find screen, if the data request is part of a data query with parameters, in standard PostData format.

Phase 3:

The device then sends a list of the primary keys of the records received, and also any records that have been deleted by the user. This list is used to update the database with a new status on these records

updateReceivedRecords()

updateRecordsRemovedFromDevice();

Connector Interface

public void init(ServerData serverData, MapProject proj, DeployProperties projectProperties ) throws MapException

called once upon server startup and project publish

public void shutDown()

called when the server or server instance, shuts down, or if the project is changed

public boolean testConnection(List<String> errors)

can be used to check connectivity with the datasource – called from Test Connection in DragonRAD Designer and from the server admin pages. Return true if the datasource if connected ok. The list of messages can be populated by the function and will be shown to user if not empty

public Maptable getRecords(MobileParameters mobileParams, List<Mapfield>queryData, List<Mappk> pksInDevice, Maptable returnedTable)

returns a list of records (returnedTable) to the device. The function should populate this table based on the synch rule being run, and parameters supplied. The synch rule "Get All" and "Get New", and user defined synch rules, for example to Find Records, will call this function to retrieve records from database.The queryData is used in Find screens and contains any data on the form as a list of fields and values. If you are using a Logon application, then the loggedOnUserData row is available in the mobileParams parameters list, e.g. mobileParams.getParameter("users.name"), where "users" is the table of the data row containg the login information, and "name" is one of the fields - all the fields will be available for use by the plugin

public Maptable updateRecords(MobileParameters mobileParams, Maptable dataRecordsFromBerry)

The device is sending a list of records to be updated. When a record is updated , or a record is deleted, or a new record is added, the function will be called.

public void updateReceivedRecords(MobileParameters mobileParams, List<Mappk> received_pks)

The device has received a list of records during the getRecords function, and is confirming that the records were received. This may be useful to change the status of these records to say status='ondevice'.

public void updateRecordsRemovedFromDevice(MobileParameters mobileParams, List<Mappk> deleted_pks)

The device has recieved a list of records to delete during the getRecords function, and is confirming that the records were deleted. This may be useful to change the status of these records.

public List<String> getDevicesWithNewRecords(MapTable table, MapSynchPolicy policy)

used in data polling for the data push capability, returns list of PINS for devices to notify of new data waiting

public String[] getPropertyNames()

returns an array of property names that should appear in the Deploy Settings page on both Designer and the Host admin pages. This allows web service urls etc to be configured during publish.

public String getStatusPage()

returns custom html that will show status of the connector on the admin page

public String getVersion()

public DCCapabilities getCapability(DCFunctions functionid)

used to define which functions are implemented. Functions not implemented should return CP_NOTIMPLEMENTED, or CP_USEDB to allow a database connector to handle the request – e.g. if the data connector handles updates but direct sql connection is being used to supply data. Return one of the CP functions.

public enum DCCapabilities {
CP_OK ,
CP_USEDB ,
CP_NOTIMPLEMENTED
}

public enum DCFunctions {
FN_GETRECORDS ,
FN_UPDATERECORDS ,
FN_UPDATERECEIVEDRECORDS ,
FN_UPDATERECORDSREMOVED
}

public MapTableList getMetaData()

used to provide a list of available tables and fields to the Designer Field Wizard

Objects

MapTable

public Maprecords getRecords()
public void setRecords(Maprecords value)
public Mapdeleted getDeleted()
public void setDeleted(Mapdeleted value)
public String getName()
public void setName(String value)

MapRecords

public List<Maprecord> getRecord() /* Return a List of Maprecord; if null, an ArrayList of Maprecord will be created and returned.*/

MapDetailRecords

public List<Maprecord> getDetailrecord() /* Return a List of Maprecord; if null, an ArrayList of Maprecord will be created and returned.*/
public String getField() /*Reture the field in parent table that the Mapdetailrecords are related to.*/
public void setField(String value) /*Set the field in parent table that the Mapdetailrecords are related to.*/

MapRecord

public Mapfields getFields()
public void setFields(Mapfields value)
public List<Mapdetailrecords> getDetailrecords() /* Return a List of Mapdetailrecords; if null, an ArrayList of Mapdetailrecords will be created and returned.*/
public String getPk()
public void setPk(String value)
public boolean isNewrecord()
public void setNewrecord(Boolean value)
public boolean isDeleted()
public void setDeleted(Boolean value)
public boolean isError()
public void setError(Boolean value)
public String getOrigpk() /*Return the pk defined by a device.*/
public void setOrigpk(String value)
public void clearFields() /*Clear all Fields of the Record.*/

Mapfields

public List<Mapfield> getField() /* Return a List of Mapfield; if null, an ArrayList of Mapfield will be created and returned.*/

Mapfield

public String getName()
public void setName(String value)
public String getValue()
public void setValue(String value)
public byte[] getBinaryValue()
public void setBinaryValue(byte[] value)

Mapdeleted

public List<Mappk> getPk() /* Return a List of Mappk; if null, an ArrayList of Mappk will be created and retured.*/

Mappk

public String getValue()
public void setValue(String value)

MobileParameters

public String getPin()
public String getUsername() (not used)
public String getPassword() (not used)
public String getGps()
public String getTimeStamp()
public String getRuleName()
public String getTableName()
public String getParameter() - used to return loggedonUserData

MapTableList

List<MapTable> getTable() /* Return a List of MapTable objects, used to provide a list of fields and field types for each table available */

Comments:

Note, please check the forum if you have questions or email support@dragonrad.com