MyCompose (Oracle Database Mobile Server API Specification)

java.lang.Object
- oracle.lite.sync.MyCompose

```
public abstract class MyCompose
extends java.lang.Object
```
Overview

MyCompose is an abstract class which provides a framework for developers to plug in customized DML composition. The composition takes as input the server side base table DML logs and produces publication item DML operations to be sent to a mobile client device. Customized composition is needed for some publication items usually for performance reasons.

Introduction

One of the core tasks of the Consolidator data synchronization is to compute DML operations for a client subscription to a publication item (a table or a view). Given physical DML logs on the server side base tables, it's not a trivial task for this so called compose phase to figure out the DML operations for each client in a generic way. For example, depending on the data sub-setting query definition of the publication item, a physical update on a base table could be an insert, a delete, or an update on the publication item for a given client.
For complex data sub-setting queries, determining client DML can also be very costly if implemented in a generic way which is what the default implementation has to follow. On the other hand, the application developer, with the knowledge of the application logic, usually is able to determine a more efficient way to accomplish the same thing for a specific publication item. Therefore, we design the compose component in such a way that an application developer can easily plug in his customized compose code.

Description

If an application developer wants to customize the compose phase for a publication item, he needs to create a compose class, e.g. ItemACompose, by extending the MyCompose class provided here. (MyCompose is an abstract class which serves as the super class for all custom compose classes.) In ItemACompose, one or more of the four MyCompose methods (init, destroy, needCompose and doCompose) can be overwritten. The developer can then call Consolidator admin API function RegisterMyCompose(String publication, String pubItem, String className, boolean reloadBytecode) to load this class, ItemACompose, to the database and attach it to the publication/publication item combination. Consolidator will load the registered class from the database at run time to do compose of the publication item for related clients. During each round of composition, base table logs are prepared for a publication item and init() is called once. Then needCompose() and doCompose() are called once for each client. At the end destroy() is called.
Besides the four methods to be overwritten, MyCompose also provides many other methods to assist the overitten methods to carry out their task: converting the physical base table DML operations into client publication item DML operations.
```
                             ----------------------
                            |   class MyCompose    |
                             ----------------------
                                         |
                                         +
                              --------------------
    Base table DML ops  ==>  | class ItemACompose |  ==> client pub item DML ops
                              --------------------
    
```
For efficiency, the physical base table DML and client publication item DML are not passed in/out as method arguments. Instead, they remain in the database tables to avoid the round trip to and from the mobile server. We provide interface to their containing tables in MyCompose class so the user code can embed them in its dynamic SQL statements.

Example 1
```
   public class ItemACompose extends MyCompose
   {
       public ItemACompose(){
       }
       public void init(Connection conn){
           ...
       }
       public int needCompose(Connection conn, Connection rmt_conn, String clientid){
           ...
           return YES;
       }
       public int doCompose(Connection conn, Connection rmt_conn, String clientid){
           ...
           return n;
       }
       public void destroy(Connection conn){
           ...
       }
   }
    
```
Example 2
Illustrates a custom MyCompose implementation that works fine regardless of whether the pub-item is defined against the MAIN repos or an app database. This is only meant to show one possible way of using the connection params properly in doCompose. The implementation for other overriden methods init, destroy and needCompose is not shown.
```
        public class ItemBCompose extends MyCompose {
           public ItemBCompose() {
           }

           public void init(Connection conn) {
               ...
           }

           public void destroy(Connection conn) {
               ...
           }

           public int needCompose(Connection conn, Connection rmtConn, String clientid) throws Throwable {
               ...
           }

           public int doCompose(Connection conn, Connection rmtConn, String clientid) throws Throwable {
               int rowCount = 0;

               //If pub-item is defined against MAIN db, auxConn will refer to MAIN db. Otherwise it
               //will refer to the app db against which the pub-item is defined.
               Connection auxConn = rmtConn;
               if(auxConn == null)
                   auxConn = rmtConn;

               String[][] baseTables = getBaseTables();
               String baseTableDMLLogName = 
               getBaseTableDMLLogName(baseTables[0][0], baseTables[0][1]);
               String baseTablePK = 
                    getBaseTablePK(baseTables[0][0], baseTables[0][1]);
               String pubItemDMLTableName = getPubItemDMLTableName();
               String pubItemPK = getPubItemPK();
               String mapView = getMapView(clientid);

               Statement st = auxConn.createStatement();
               String sql = null;

               // insert, delete
               sql = 
                     "INSERT INTO " + pubItemDMLTableName + " SELECT " + baseTablePK + ", DMLTYPE$$ FROM " + 
                       baseTableDMLLogName;

               rowCount += st.executeUpdate(sql);

               // update 
               sql = 
                     "UPDATE " + pubItemDMLTableName + " SET DMLTYPE$$='U' WHERE (" + pubItemPK + 
                       ") IN (SELECT " + pubItemPK + " FROM " + mapView + " WHERE CLID$$CS='" + 
                       clientid + "')" + " AND DMLTYPE$$='I'";
               rowCount += st.executeUpdate(sql);

               st.close();
               return rowCount;
            }
        }
    
```
Since:

5.0.2.0.0

Field Summary

Fields
Modifier and Type Field and Description

static int NO

static oracle.lite.common.NLSResources RESOURCES

static int YES

Fields
Modifier and Type	Field and Description
`static int`	`NO`
`static oracle.lite.common.NLSResources`	`RESOURCES`
`static int`	`YES`

Constructor Summary

Constructors
Constructor and Description

MyCompose()
Abstract class Constructor, do nothing.

Constructors
Constructor and Description
`MyCompose()` Abstract class Constructor, do nothing.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`baseTableDirty(java.lang.String owner, java.lang.String store)` Whether the base table has changes.
`static void`	`deRegisterMyCompose(java.sql.Connection conn, java.lang.String publication, java.lang.String pubItem, boolean removeBytecode)` Called by Consolidator Admin API to deRegister a customized compose class.
`void`	`destroy(java.sql.Connection conn)` May be overwritten by a subclass to do compose cleanups for a publication, pubitem pair.
`int`	`doCompose(java.sql.Connection conn, java.sql.Connection rmt_conn, java.lang.String clientid)` May be overwritten by a subclass to do compose for a client.
`int`	`doCompose(java.sql.Connection conn, java.sql.Connection rmt_conn, java.lang.String clientid, java.lang.String group, boolean seq_incr)`
`java.lang.String`	`getBaseTableDMLLogName(java.lang.String owner, java.lang.String baseTable)` Returns physical DML log table or view name for a base table.
`java.lang.String`	`getBaseTablePK(java.lang.String owner, java.lang.String baseTable)` Returns comma separated base table primary key.
`java.lang.String[][]`	`getBaseTables()` Returns all the base tables for the publication item.
`java.lang.String`	`getMapView(java.lang.String clientid)` Returns a view of the map table.
`java.lang.String`	`getPubItemDMLTableName()` Returns publication item DML table or view name.
`java.lang.String`	`getPubItemPK()` Returns comma separated publication item primary key.
`java.lang.String`	`getPublication()` Returns publication name
`java.lang.String`	`getPublicationItem()` Returns publication item name
`int`	`hasComposedData(java.sql.Connection conn, java.sql.Connection rmt_conn, java.lang.String clientid)`
`void`	`init(java.sql.Connection conn)` May be overwritten by a subclass to do compose preparation for a publication, pubitem pair.
`int`	`needCompose(java.sql.Connection conn, java.sql.Connection rmt_conn, java.lang.String clientid)` May be overwritten by a subclass to tell Consolidator whether there are any new changes for a client.
`static void`	`registerMyCompose(java.sql.Connection conn, java.sql.Connection rmtConn, java.lang.String publication, java.lang.String pubItem, java.lang.String className, boolean reloadBytecode)` Called by Consolidator Admin API to register and load to DB a customized compose class.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NO
```
public static final int NO
```
    See Also:
    Constant Field Values
  - RESOURCES
```
public static oracle.lite.common.NLSResources RESOURCES
```
  - YES
```
public static final int YES
```
    See Also:
    Constant Field Values
- Constructor Detail
  - MyCompose
```
public MyCompose()
```
    Abstract class Constructor, do nothing.
- Method Detail
  - baseTableDirty
```
public boolean baseTableDirty(java.lang.String owner,
                     java.lang.String store)
```
    Whether the base table has changes.
    
    Parameters:
    owner - base table schema name
    store - base table name
    
    Returns:
    true if the base table has changes
  - deRegisterMyCompose
```
public static void deRegisterMyCompose(java.sql.Connection conn,
                       java.lang.String publication,
                       java.lang.String pubItem,
                       boolean removeBytecode)
                                throws java.lang.Exception
```
    Called by Consolidator Admin API to deRegister a customized compose class.
    
    Parameters:
    conn - Database connection
    publication - Publication name
    pubItem - Publication item name
    removeBytecode - If true then bytecode of the registered class is removed from the database.
    
    Throws:
    
    java.lang.Exception
  - destroy
```
public void destroy(java.sql.Connection conn)
```
    May be overwritten by a subclass to do compose cleanups for a publication, pubitem pair. Default implementation: do nothing. This is called once for all clients right after compose.
    
    Parameters:
    conn - Database connection to Consolidator repository
  - doCompose
```
public int doCompose(java.sql.Connection conn,
            java.sql.Connection rmt_conn,
            java.lang.String clientid)
              throws java.lang.Throwable
```
    May be overwritten by a subclass to do compose for a client. The method will populate the logical DML log table of the publication item for the client. This is called once for each client.
    
    Parameters:
    conn - Connection to MAIN repository
    rmt_conn - Connection to the app database. MGP will set it to null if pub-item base tables are in the MAIN db. If rmt_conn is not null, it should be used to populate publication item DML table and it should not be committed or rolled back inside the method. If rmt_conn is null, conn should be used as all concerned tables are in MAIN db.
    clientid - client id
    
    Returns:
    number of DML operations
    
    Throws:
    
    java.lang.Throwable
    Since:
    
    10.3.0.2
  - doCompose
```
public int doCompose(java.sql.Connection conn,
            java.sql.Connection rmt_conn,
            java.lang.String clientid,
            java.lang.String group,
            boolean seq_incr)
              throws java.lang.Throwable
```
    Throws:
    
    java.lang.Throwable
  - getBaseTableDMLLogName
```
public java.lang.String getBaseTableDMLLogName(java.lang.String owner,
                                      java.lang.String baseTable)
```
    Returns physical DML log table or view name for a base table. User may embed the returned value into dynamic SQL statements. For one publication item there might be multiple base tables and hence multiple physical logs. The parent base table's physical PK corresponds to the publication item PK. The structure of the log is:
```
  <Base TAble PK> DMLTYPE$$
  
```
    where DMLTYPE$$ may have values 'I' for insert and update and 'D' for delete.
    Parameters:
    owner - base table owner schema name
    baseTable - base table name
    
    Returns:
    physical log table or view name including schema name. Note that the view could be an in-line view.
  - getBaseTablePK
```
public java.lang.String getBaseTablePK(java.lang.String owner,
                              java.lang.String baseTable)
                                throws java.lang.Throwable
```
    Returns comma separated base table primary key.
    
    Parameters:
    owner - base table owner schema name
    baseTable - base table name
    
    Returns:
    base table primary key in the form of <col1>,<col2>,<col3>
    
    Throws:
    
    java.lang.Throwable
  - getBaseTables
```
public java.lang.String[][] getBaseTables()
                                   throws java.lang.Throwable
```
    Returns all the base tables for the publication item.
    
    Returns:
    An array of two string arrays. Each two string array contains the schema name and the base table name. The first base table in the array, i.e. baseTables[0], is the parent table.
    
    Throws:
    
    java.lang.Throwable
  - getMapView
```
public java.lang.String getMapView(java.lang.String clientid)
                            throws java.lang.Throwable
```
    Returns a view of the map table. User may embed the returned value into dynamic SQL statements. The map table contains a PK list for each client device and other information. The structure of the map view is:
```
  CLID$$CS <Pub Item PK> DMLTYPE$$
  
```
    where CLID$$CS is the client id and DMLTYPE$$ may have values I, D or U for insert, delete and update respectively.
    Parameters:
    clientid - client id
    
    Returns:
    a view of the map table. Note that the view could be an in-line view.
    
    Throws:
    
    java.lang.Throwable
  - getPubItemDMLTableName
```
public java.lang.String getPubItemDMLTableName()
```
    Returns publication item DML table or view name. This is the table or view which doCompose() and/or init() is supposed to populate (insert to). The table is supposed to be empty before customized compose takes place. User may embed the returned value into dynamic SQL statements. The structure of the table (or view) is:
```
  <PubItem PK> DMLTYPE$$
  
```
    where DMLTYPE$$ may have values I, D or U for insert, delete and update respectively. "PubItem PK" can be retrieved using getPubItemPK().
    Returns:
    publication item DML table or view name including schema name. Note that the view could be an in-line view.
  - getPubItemPK
```
public java.lang.String getPubItemPK()
                              throws java.lang.Throwable
```
    Returns comma separated publication item primary key.
    
    Returns:
    publication item primary key in the form of <col1>,<col2>,<col3>
    
    Throws:
    
    java.lang.Throwable
  - getPublication
```
public java.lang.String getPublication()
```
    Returns publication name
    
    Returns:
    Publication name
  - getPublicationItem
```
public java.lang.String getPublicationItem()
```
    Returns publication item name
    
    Returns:
    Publication item name
  - hasComposedData
```
public int hasComposedData(java.sql.Connection conn,
                  java.sql.Connection rmt_conn,
                  java.lang.String clientid)
                    throws java.lang.Throwable
```
    Parameters:
    conn - Connection to MAIN repository
    rmt_conn - Connection to app database. If pub-item is defined against MAIN datbase, MGP passes a null value for this parameter when it invokes this method.
    clientid - client id
    
    Returns:
    YES or NO. If returns NO, doCompose() will
    
    Throws:
    
    java.lang.Throwable
    Since:
    
    10.3.0.2
  - init
```
public void init(java.sql.Connection conn)
```
    May be overwritten by a subclass to do compose preparation for a publication, pubitem pair. Default implementation: do nothing. This is called once for all clients right before compose.
    
    Parameters:
    conn - Database connection to Consolidator repository
  - needCompose
```
public int needCompose(java.sql.Connection conn,
              java.sql.Connection rmt_conn,
              java.lang.String clientid)
                throws java.lang.Throwable
```
    May be overwritten by a subclass to tell Consolidator whether there are any new changes for a client. This is called once for each client. Default implementation: return YES.
    
    Parameters:
    conn - Connection to MAIN repository
    rmt_conn - Connection to app database. If pub-item is defined against MAIN datbase, MGP passes a null value for this parameter when it invokes this method.
    clientid - client id
    
    Returns:
    YES or NO. If returns NO, doCompose() will not be called.
    
    Throws:
    
    java.lang.Throwable
    Since:
    
    10.3.0.2
  - registerMyCompose
```
public static void registerMyCompose(java.sql.Connection conn,
                     java.sql.Connection rmtConn,
                     java.lang.String publication,
                     java.lang.String pubItem,
                     java.lang.String className,
                     boolean reloadBytecode)
                              throws java.lang.Throwable
```
    Called by Consolidator Admin API to register and load to DB a customized compose class. If either publication or pubItem is null, the class will not be associated (registered) to a publication/pubItem pair. However, the class bytecode will still be loaded to the database repository and can be referenced by registered compose classes.
    
    Parameters:
    conn - Database connection to repository (main db)
    rmtConn - Database connection to app db (null if app schema is in main db)
    publication - Publication name
    pubItem - Publication item name
    className - MyCompose subclass name
    reloadBytecode - If true then existing bytecode of the class (in DB) is overwritten.
    
    Throws:
    
    java.lang.Throwable

Class MyCompose

Overview

Introduction

Description

Example 1

Example 2

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NO

RESOURCES

YES

Constructor Detail

MyCompose

Method Detail

baseTableDirty

deRegisterMyCompose

destroy

doCompose

doCompose

getBaseTableDMLLogName

getBaseTablePK

getBaseTables

getMapView

getPubItemDMLTableName

getPubItemPK

getPublication

getPublicationItem

hasComposedData

init

needCompose

registerMyCompose