SaveOperation (sormula)

java.lang.Object
- org.sormula.operation.SqlOperation<R>
- - org.sormula.operation.ModifyOperation<R>
  - - org.sormula.operation.SaveOperation<R>

Type Parameters:

R - class type which contains members for columns of a row in a table

All Implemented Interfaces:

java.lang.AutoCloseable
```
public class SaveOperation<R>
extends ModifyOperation<R>
```
SQL update or insert operation for row of type R. Rows are updated if they exist in the database or inserted if they are new rows. Cascades are performed based upon Cascade.saves(), OneToManyCascade.saves(), or OneToOneCascade.saves().
Inserts and updates are performed by class members of type InsertOperation and UpdateOperation. Since most of the work is delegated to InsertOperation and UpdateOperation, not all methods of base class ModifyOperation are used. All of the methods in SaveOperation may be safely overridden but some subclass methods may not be used.

Since:

1.1

Author:

Jeff Miller

Constructor Summary

Constructors
Constructor and Description
`SaveOperation(Table<R> table)` Constructs to update by primary key or insert if update fails.
`SaveOperation(Table<R> table, boolean identity)` Constructs to update by primary key or insert if update fails.
`SaveOperation(Table<R> table, boolean identity, java.lang.String whereConditionName)` Constructs to update by where condition or insert if update fails.
`SaveOperation(Table<R> table, java.lang.String whereConditionName)` Constructs to update by where condition or insert if update fails.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Cleans up after operation is no longer needed.
`void`	`execute()` Executes by updating all row(s) using `UpdateOperation`.
`int[]`	`getModifyCounts()` For each row saved, gets modify counts either from `ModifyOperation.getModifyCounts()` if row was updated or from `ModifyOperation.getModifyCounts()` if row was inserted.
`void`	`notifyCacheModified(R row)` Delegates to `Cache.inserted(Object)`, `Cache.updated(Object)`, `Cache.deleted(Object)` based upon the subclass operation.
`protected boolean`	`notifyCacheModify(R row)` Delegates to `Cache.insert(Object)`, `Cache.update(Object)`, `Cache.delete(Object)` based upon the subclass operation.
`protected void`	`postExecute(R row)` Invoked after JDBC execute.
`protected void`	`postExecuteCascade(R row)` Invoked after JDBC execute.
`protected void`	`preExecute(R row)` Invoked prior to JDBC execute.
`protected void`	`preExecuteCascade(R row)` Invoked prior to JDBC execute.
`protected java.util.List<CascadeOperation<R,?>>`	`prepareCascades(java.lang.reflect.Field field)` Creates save cascade operations based upon the save annotations for field.
`int`	`save(java.lang.Object... parameters)` Saves rows based upon parameters.
`int`	`save(R row)` Saves a row.
`int`	`saveAll(java.util.Collection<R> rows)` Saves all rows in collection.
`void`	`setBatch(boolean batch)` Sets batch state for internal insert and update operations.
`void`	`setCached(boolean cached)` Sets cached enabled state for internal insert and update operations.
`void`	`setCascade(boolean cascade)` Sets cascade state for internal insert and update operations.

Methods inherited from class org.sormula.operation.ModifyOperation
getRows, getRowsAffected, isBatch, modify, modify, modifyAll, setParameters, setRow, setRows, setRows, setRows, setRowsAffected

Methods inherited from class org.sormula.operation.SqlOperation
cancel, cascade, closeCascades, closeStatement, createRowField, getBaseSql, getCascadeDepth, getConnection, getCustomSql, getNamedParameterMap, getNextParameter, getOperationTime, getParameter, getParameters, getPreparedSql, getPreparedStatement, getQueryTimeout, getRequiredCascades, getSql, getTable, getTargetTable, getTimingId, getWhereAnnotation, getWhereConditionName, getWhereTranslator, initOperationTime, isCached, isCascade, isCascading, isIncludeIdentityColumns, isPrimaryKey, isReadOnly, isRequiredCascade, isTimings, logTimings, prepare, prepareCascades, prepareCheck, prepareStatement, setBaseSql, setCascadeDepth, setCustomSql, setIncludeIdentityColumns, setNamedParameterMap, setNextParameter, setParameter, setQueryTimeout, setReadOnly, setRequiredCascades, setTimingId, setTimings, setWhere, setWhereTranslator, writeColumns, writeParameter, writeParameters, writeWhere

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

- Constructor Detail
  - SaveOperation
```
public SaveOperation(Table<R> table)
              throws OperationException
```
    Constructs to update by primary key or insert if update fails.
    
    Parameters:
    
    table - update/insert to this table
    
    Throws:
    
    OperationException - if error
  - SaveOperation
```
public SaveOperation(Table<R> table,
                     boolean identity)
              throws OperationException
```
    Constructs to update by primary key or insert if update fails.
    This constructor is equivalent to SaveOperation(Table, boolean, "primaryKey"). Use this constructor when you want identity columns to be inserted without using autogenerated keys (use false for identity parameter).
    
    Parameters:
    
    table - update/insert to this table
    
    identity - true to insert using autogenerated keys for identity columns; false to insert identity columns as without generating key
    
    Throws:
    
    OperationException - if error
    
    Since:
    
    4.1
  - SaveOperation
```
public SaveOperation(Table<R> table,
                     java.lang.String whereConditionName)
              throws OperationException
```
    Constructs to update by where condition or insert if update fails. Inserts use autogenerated keys for identity columns. This constructor is equivalent to SaveOperation(Table, true, String).
    
    Parameters:
    
    table - update/insert to this table
    
    whereConditionName - name of where condition to use for update ("primaryKey" to update by primary key; empty string to update all rows in table)
    
    Throws:
    
    OperationException - if error
  - SaveOperation
```
public SaveOperation(Table<R> table,
                     boolean identity,
                     java.lang.String whereConditionName)
              throws OperationException
```
    Constructs to update by where condition or insert if update fails.
    Use this constructor when you want identity columns to be inserted without using autogenerated keys (use false for identity parameter).
    
    Parameters:
    
    table - update/insert to this table
    
    identity - true to insert using autogenerated keys for identity columns; false to insert identity columns as without generating key
    
    whereConditionName - name of where condition to use for update ("primaryKey" to update by primary key; empty string to update all rows in table)
    
    Throws:
    
    OperationException - if error
    
    Since:
    
    4.1
- Method Detail
  - close
```
public void close()
           throws OperationException
```
    Description copied from class: ModifyOperation
    
    Cleans up after operation is no longer needed. The connection is not closed but all other objects created by this operations are closed. Prepared statement is closed and close method is invoked on all CascadeOperation objects. This method should be invoked when operation is no longer needed for proper JDBC clean up.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Overrides:
    
    close in class ModifyOperation<R>
    
    Throws:
    
    OperationException - if error
  - getModifyCounts
```
public int[] getModifyCounts()
```
    For each row saved, gets modify counts either from ModifyOperation.getModifyCounts() if row was updated or from ModifyOperation.getModifyCounts() if row was inserted.
    
    Overrides:
    
    getModifyCounts in class ModifyOperation<R>
    
    Returns:
    
    modify counts of all rows processed; each element is associated with one row processed
    
    Since:
    
    4.1
  - setBatch
```
public void setBatch(boolean batch)
```
    Sets batch state for internal insert and update operations.
    
    Overrides:
    
    setBatch in class ModifyOperation<R>
    
    Parameters:
    
    batch - true for batch save
    
    Since:
    
    3.0
    
    See Also:
    
    Statement.executeBatch()
  - setCached
```
public void setCached(boolean cached)
```
    Sets cached enabled state for internal insert and update operations.
    
    Overrides:
    
    setCached in class SqlOperation<R>
    
    Parameters:
    
    cached - true to enable cache; false to turn off caching
    
    Since:
    
    3.0
  - setCascade
```
public void setCascade(boolean cascade)
```
    Sets cascade state for internal insert and update operations.
    
    Overrides:
    
    setCascade in class SqlOperation<R>
    
    Parameters:
    
    cascade - true to allow cascades to occur; false for no cascading
    
    Since:
    
    3.0
  - save
```
public int save(R row)
         throws OperationException
```
    Saves a row. Set parameters, executes, closes. Alias for ModifyOperation.modify(Object).
    
    Parameters:
    
    row - row to use for parameters
    
    Returns:
    
    ModifyOperation.getRowsAffected()
    
    Throws:
    
    OperationException - if error
    
    Since:
    
    1.4
  - saveAll
```
public int saveAll(java.util.Collection<R> rows)
            throws OperationException
```
    Saves all rows in collection. Set parameters, executes, closes. Alias for ModifyOperation.modifyAll(Collection).
    
    Parameters:
    
    rows - collection of rows to use as parameters
    
    Returns:
    
    ModifyOperation.getRowsAffected()
    
    Throws:
    
    OperationException - if error
    
    Since:
    
    1.4
  - save
```
public int save(java.lang.Object... parameters)
         throws OperationException
```
    Saves rows based upon parameters. Set parameters, executes, closes. Alias for ModifyOperation.modify(Object...).
    
    Parameters:
    
    parameters - operation parameters as objects (see ModifyOperation.setParameters(Object...))
    
    Returns:
    
    count of rows affected
    
    Throws:
    
    OperationException - if error
    
    Since:
    
    1.4
  - execute
```
public void execute()
             throws OperationException
```
    Executes by updating all row(s) using UpdateOperation. For all rows that are not updated, uses InsertOperation to insert them.
    
    Overrides:
    
    execute in class ModifyOperation<R>
    
    Throws:
    
    OperationException - if error
    
    BatchException - for batch operations if EXECUTE_FAILED is returned
    
    BatchException - for batch operations if SUCCESS_NO_INFO is returned and cascading is needed
    
    BatchException - for batch operations if SUCCESS_NO_INFO is returned for update
  - prepareCascades
```
protected java.util.List<CascadeOperation<R,?>> prepareCascades(java.lang.reflect.Field field)
                                                         throws OperationException
```
    Creates save cascade operations based upon the save annotations for field.
    
    Specified by:
    
    prepareCascades in class SqlOperation<R>
    
    Parameters:
    
    field - annotation is for this field of row class R
    
    Returns:
    
    list of save cascade operations; empty list for none
    
    Throws:
    
    OperationException - if error
    
    Since:
    
    1.9.3 and 2.3.3
  - preExecute
```
protected void preExecute(R row)
                   throws OperationException
```
    Invoked prior to JDBC execute. Override to modify the row prior to JDBC execute. Default implementation does nothing. This method is not invoked when ModifyOperation.setParameters(Object...) is used since no row is available.
    
    Overrides:
    
    preExecute in class ModifyOperation<R>
    
    Parameters:
    
    row - row for JDBC execute
    
    Throws:
    
    OperationException - if error
  - postExecute
```
protected void postExecute(R row)
                    throws OperationException
```
    Invoked after JDBC execute. Override to modify the row after JDBC execute has occurred. Default implementation does nothing. This method is not invoked when ModifyOperation.setParameters(Object...) is used since no row is available.
    
    Overrides:
    
    postExecute in class ModifyOperation<R>
    
    Parameters:
    
    row - row for JDBC execute
    
    Throws:
    
    OperationException - if error
  - preExecuteCascade
```
protected void preExecuteCascade(R row)
                          throws OperationException
```
    Invoked prior to JDBC execute. Performs all modify cascade operations where post flag is false.
    
    Overrides:
    
    preExecuteCascade in class ModifyOperation<R>
    
    Parameters:
    
    row - row for JDBC execute
    
    Throws:
    
    OperationException - if error
    
    See Also:
    
    InsertCascade.post(), UpdateCascade.post(), SaveCascade.post(), DeleteCascade.post()
  - postExecuteCascade
```
protected void postExecuteCascade(R row)
                           throws OperationException
```
    Invoked after JDBC execute. Performs all modify cascade operations where post flag is true.
    
    Overrides:
    
    postExecuteCascade in class ModifyOperation<R>
    
    Parameters:
    
    row - row for JDBC execute
    
    Throws:
    
    OperationException - if error
    
    See Also:
    
    InsertCascade.post(), UpdateCascade.post(), SaveCascade.post(), DeleteCascade.post()
  - notifyCacheModify
```
protected boolean notifyCacheModify(R row)
                             throws OperationException
```
    Delegates to Cache.insert(Object), Cache.update(Object), Cache.delete(Object) based upon the subclass operation.
    
    Specified by:
    
    notifyCacheModify in class ModifyOperation<R>
    
    Parameters:
    
    row - row to be modified
    
    Returns:
    
    true if cache is authority for row (cache will modify row in database); false if cache does not modify the database
    
    Throws:
    
    OperationException - if error
  - notifyCacheModified
```
public void notifyCacheModified(R row)
                         throws OperationException
```
    Delegates to Cache.inserted(Object), Cache.updated(Object), Cache.deleted(Object) based upon the subclass operation.
    
    Specified by:
    
    notifyCacheModified in class ModifyOperation<R>
    
    Parameters:
    
    row - that was modified in database
    
    Throws:
    
    OperationException - if error

Class SaveOperation<R>

Constructor Summary

Method Summary

Methods inherited from class org.sormula.operation.ModifyOperation

Methods inherited from class org.sormula.operation.SqlOperation

Methods inherited from class java.lang.Object

Constructor Detail

SaveOperation

SaveOperation

SaveOperation

SaveOperation

Method Detail

close

getModifyCounts

setBatch

setCached

setCascade

save

saveAll

save

execute

prepareCascades

preExecute

postExecute

preExecuteCascade

postExecuteCascade

notifyCacheModify

notifyCacheModified