/* A DBOperation object represents a database operation. 
   It contains read-only user-visible fields.
*/

//   DBSession.buildXXX takes additional transaction and callback
//    The callback will receive(error, DBResult)


var   DBOperation,          // DBOperation structure prototype
      OperationCodes,       // Array of defined opcodes
      OperationStates,      // Array of defined operation states
      LockModes,            // Array of defined lock modes
      DBResult,             // DBResult structure prototype
      DBOperationError;     // DBOperationError structure prototype


DBOperation = {
  opcode          : null ,  // the OperationCode
  userCallback    : null ,  // a higher level callback
  transaction     : null ,  // pointer to the operation's transaction
  values          : null ,  // array or map containing user-supplied values
  tableHandler    : null ,  // the DBTableHandler used for this operation
  lockMode        : null ,  // LockMode used for a read operation
  index           : null ,  // the IndexMetadata used for this operation
  state           : null ,  // the current OperationState
  result          : null ,  // DBResult object containing the result of the operation
};

OperationCodes = {
  'OP_READ'        :  1,       1 : 'read',
  'OP_INSERT'      :  2,       2 : 'insert',
  'OP_UPDATE'      :  4,       4 : 'update',
  'OP_WRITE'       :  8,       8 : 'write',
  'OP_DELETE'      : 16,      16 : 'delete',
  'OP_SCAN'        : 32,      32 : 'scan',
  'OP_SCAN_READ'   : 33,      33 : 'scan_read',
  'OP_SCAN_COUNT'  : 34,      34 : 'scan_count',
  'OP_SCAN_DELETE' : 48,      48 : 'scan_delete'
};


OperationStates = [ 
  "DEFINED",             // opcode, table, and required keys/values are present
  "PREPARED",            // local preparation of the operation is complete
  "COMPLETED"            // operation is complete and result is available
];   


/* All LockModes may not be implemented by all adapters.
   The LockMode in the DBOperation reflects the actual supported LockMode in use 
   for the operation.
*/   
LockModes = [ 
  "EXCLUSIVE",         // Read with an exclusive lock
  "SHARED",            // Read with a shared-read lock
  "COMMITTED"          // Read committed values (no locking)
];


DBResult = { 
  success        : null ,  // boolean indicating whether the operation succeeded
  error          : null ,  // a DBOperationError object  
  value          : null ,  // Result value created according to the DBTableHandler
  insert_id      : null ,  // value of AUTO-INCREMENT key on insert
};


DBOperationError = {
  code           : null,   // MySQL Error Code number (number)
  sqlstate       : null,   // MySQL SQLSTATE (string)
  message        : null    // Error message (string)
  /* ...  Other adapter-specific properties which may be present */
};


/* This documentation file is a valid JavaScript module and exports: 
*/
exports.DBOperation = DBOperation;
exports.OperationCodes = OperationCodes;
exports.OperationStates = OperationStates;
exports.LockModes = LockModes;
exports.DBOperationError = DBOperationError;
exports.DBResult = DBResult;