Package com.jbstrap.core.meta

Class SQLDataDescriptor

java.lang.Object
com.jbstrap.core.meta.BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
com.jbstrap.core.meta.SQLDataDescriptor
All Implemented Interfaces:
DataDescriptor
public class SQLDataDescriptor extends BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>

SQL DataDescriptor

SQL DataDescriptor stores data in an SQL database and retrieves them from there using native SQL statements specified by the developer. When creating the DataDescriptor (either programmatically or from an XML file), you have to specify the SQL statements used by the DataDescriptor to fetch, save, modify or delete data. Non-specified statements result in an error. If you specify SelectStatements, then you can perform read operations only through the DataDescriptor, all other write or delete operations result in an error and are not performed.

You can specify any SQL statement for the DataDescriptor that is supported by the database, or you can use the record’s attribute values in the specified SQL statements:
Example:
If you want to use the record’s ID in the WHERE part of the UPDATE statement and you want to update the rest of the data, you can do it in the following way:
update table_name set column1 = :column1, column2 = :column2 where id = :_id;

Attributes can be used in SQL statements by attaching a colon character before the attribute name. Consequently, they are used as parameters in the specified SQL statement. The framework automatically passes the corresponding record value to these parameters when performing the query.

Since:
4.0
Author:
JBStrap
See Also:

  • Constructor Details

    • SQLDataDescriptor

      public SQLDataDescriptor(String name)
      Creates a DataDescriptor with the specified name.
      Parameters:
      name - Unique SQL DataDescriptor name
      Throws:
      NullPointerException - Thrown if null is specified for the DataDescriptor name

  • Method Details

    • getSelectStatement

      public String getSelectStatement()
      Gets the SELECT statement specified for the SQL DataDescriptor.
      Returns:
      SQL statement used by the DataDescriptor or null if no SELECT statement was specified

    • setSelectStatement

      public SQLDataDescriptor setSelectStatement(String selectStatement)
      Sets the SELECT statement specified for the SQL DataDescriptor. The specified SQL statement is used by the DataDescriptor to fetch data if you use a DataDescriptor to fetch data from the database.
      Parameters:
      selectStatement - The SQL statement used for the query If null is specified, you cannot use a DataDescriptor to fetch data from the database.
      Returns:
      SQL DataDescriptor instance

    • getInsertStatement

      public String getInsertStatement()
      Gets the SQL statement used to insert a new record.
      Returns:
      An INSERT statement specified for the DataDescriptor or null if there was no INSERT statement specified

    • setInsertStatement

      public SQLDataDescriptor setInsertStatement(String insertStatement)
      Sets the INSERT statement used to insert records in the database by the SQL DataDescriptor. The specified SQL statement uses the DataDescriptor to create the new record. In the specified SQL statement, you can use the attributes in the record. Specify these attributes in the following format: :attribute_name.
      Parameters:
      insertStatement - The SQL statement used by the DataDescriptor to insert data If null is specified, you cannot insert a new record into the database by using a DataDescriptor.
      Returns:
      SQL DataDescriptor instance

    • getUpdateStatement

      public String getUpdateStatement()
      Gets the SQL statement specified for the SQL DataDescriptor and used to insert a record.
      Returns:
      An UPDATE SQL statement specified for the DataDescriptor or null if there was no UPDATE SQL statement specified for the DataDescriptor

    • setUpdateStatement

      public SQLDataDescriptor setUpdateStatement(String updateStatement)
      Sets an UPDATE SQL statement for the SQL DataDescriptor. The specified SQL statement is used by The DataDescriptor to update a record. In the specified SQL statement, you can use the attributes in the record. Specify these attributes in the following format: :attribute_name.
      Parameters:
      updateStatement - The SQL statement used by the DataDescriptor to update a record If null is specified, you cannot update a record using a DataDescriptor.
      Returns:
      SQL DataDescriptor instance

    • getDeleteStatement

      public String getDeleteStatement()
      Gets the SQL statement specified for an SQL DataDescriptor and used to delete a record.
      Returns:
      A DELETE statement specified for the DataDescriptor or null if there was no DELETE statement specified

    • setDeleteStatement

      public SQLDataDescriptor setDeleteStatement(String deleteStatement)
      Sets an SQL statement used by the SQL DataDescriptor to delete a record. In the specified SQL statement, you can use the attributes in the record. Specify these attributes in the following format: :attribute_name.
      Parameters:
      deleteStatement - The SQL statement used by the DataDescriptor to delete a record
      Returns:
      SQL DataDescriptor instance

    • find

      public List<Record> find(SQLTransaction transaction, Client client, Criteria criteria, List<Order> orders, int startRow, int endRow) throws FindException, DataAccessException
      Initiates a query by using the DataDescriptor.
      Specified by:
      find in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Parameters:
      transaction - Transaction object used to initiated the query If null is specified, the query does not use a transaction (it takes place outside of a transaction).
      client - The client instance initiating the query If null is specified, user access to the data is not checked.
      startRow - The index of the first row
      endRow - The index of the last row
      criteria - Criteria instance used as a filter criterion If null is specified, the query fetches all records from the database without filtering.
      orders - A list containing Order objects used to the order the query results If null or an empty list is passed, the query results are not ordered.
      Returns:
      A list of Record instances returned by the query
      Throws:
      FindException - Occurs if an error was encountered during the query
      DataAccessException - Occurs if the user in the specified client has no access to read the data

    • countData

      public long countData(SQLTransaction transaction, Client client, Criteria criteria) throws RowCountException, DataAccessException
      Gets the number of the record in the database.
      Specified by:
      countData in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Parameters:
      transaction - Transaction object used to initiated the query If null is specified, the query does not use a transaction (it takes place outside of a transaction).
      client - The client instance initiating the query If null is specified, user access to the data is not checked.
      criteria - Criteria instance used as a filter criterion If null is specified, the query fetches all records from the database without filtering.
      Returns:
      The number of records corresponding to the specified criteria If no records correspond to the specified criteria, the method returns 0.
      Throws:
      RowCountException - Occurs if an error was encountered during the execution of the SQL instruction that does the counting.
      DataAccessException - Occurs if the logged in user has no read access to the DataDescriptor

    • save

      public List<Record> save(SQLTransaction transaction, Client client, List<Record> records) throws SaveException, DataAccessException
      Initiates a save operation using a DataDescriptor.
      Use the method to save one or more records to the database using the DataDescriptor.
      Specified by:
      save in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Parameters:
      transaction - Transaction object used to initiated the query If null is specified, the query does not use a transaction (it takes place outside of a transaction).
      client - The client instance initiating the query If null is specified, user access to the data is not checked.
      records - A list of records to be saved
      Returns:
      The saved record
      Throws:
      SaveException - Occurs if an error was encountered during the save.
      DataAccessException - Occurs if the user on the specified client has no permission to save the record to the DataDescriptor.

    • remove

      public List<Record> remove(SQLTransaction transaction, Client client, List<Record> records) throws RemoveException, DataAccessException
      Initiates a delete operation by using a DataDescriptor.
      Use the method to delete one or more records from the database using a DataDescriptor.
      Specified by:
      remove in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Parameters:
      transaction - Transaction object used to initiated the query If null is specified, the query does not use a transaction (it takes place outside of a transaction).
      client - The client instance initiating the query If null is specified, user access (and whether the user has rights to write the data) to the data is not checked.
      records - A list of records to be deleted
      Throws:
      RemoveException - Occurs if an error was encountered during the removal process
      DataAccessException - Occurs if the user on the specified client has no access to write the data of the DataDescripor.

    • findById

      public Record findById(SQLTransaction transaction, Client client, Object... id) throws FindException, DataAccessException
      Fetches a record from the database using the record’s unique ID.
      Specified by:
      findById in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Parameters:
      transaction - Transaction object used to initiated the query If null is specified, the query does not use a transaction (it takes place outside of a transaction).
      client - The client instance initiating the query If null is specified, user access to the data is not checked.
      id - Record ID
      Throws:
      FindException - Occurs if an error was encountered during the query
      DataAccessException - Occurs if the user in the specified client has no access to query the data.

    • openTransaction

      public SQLTransaction openTransaction()
      Initiates a transaction with the DataDescriptor type.
      Specified by:
      openTransaction in interface DataDescriptor
      Specified by:
      openTransaction in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Returns:
      New database transaction object

    • copy

      public SQLDataDescriptor copy()
      Creates a copy of the DataDescriptor
      Specified by:
      copy in interface DataDescriptor
      Overrides:
      copy in class BaseDataDescriptor<SQLDataDescriptor,SQLTransaction>
      Returns:
      A new DataDescriptor, that is a perfect copy of the DataDescriptor