Package org.synchronoss.cpo.core

Interface CpoAdapter

All Superinterfaces:
Serializable
All Known Subinterfaces:
CpoTrxAdapter
All Known Implementing Classes:
CassandraCpoAdapter, CpoBaseAdapter, JdbcCpoAdapter, JdbcCpoTrxAdapter, JdbcCpoXaAdapter
public interface CpoAdapter extends Serializable
CpoAdapter is an interface for a set of routines that are responsible for Creating, Retrieving, Updating, and Deleting (CRUD) value beans within a datasource.

CpoAdapter is an interface that acts as a common facade for different datasources. It is conceivable that an CpoAdapter can be implemented for JDBC, CSV, XML, LDAP, and more datasources.

Every operation exists in a canonical form taking a CpoQuery — which carries the function group name and any run-time where constraints, orderings, and native expressions — plus convenience forms for the common no-clause cases. Example: 


 CpoAdapter cpo = CpoAdapterFactoryManager.getCpoAdapter("myContext");
 CpoWhere where = cpo.newWhere(Logical.NONE, "id", Comparison.EQ, 42);
 try (Stream<SomeBean> beans =
     cpo.retrieveBeans(CpoQuery.group("byId").where(where), criteria)) {
   beans.forEach(...);
 }

The examples on the methods below assume a cpo adapter obtained as above and a SomeBean class mapped in the meta data.

Author:
david berry

  • Method Summary

    Modifier and Type
    Method
    Description
    default <T> long
    deleteBean(String groupName, T bean)
    Removes the bean from the datasource using the named DELETE function group.
    <T> long
    deleteBean(CpoQuery query, T bean)
    Removes the bean from the datasource using the query's DELETE function group.
    default <T> long
    deleteBean(T bean)
    Removes the bean from the datasource using the default DELETE function group.
    default <T> long
    deleteBeans(String groupName, List<T> beans)
    Removes the beans from the datasource using the named DELETE function group.
    default <T> long
    deleteBeans(List<T> beans)
    Removes the beans from the datasource using the default DELETE function group.
    <T> long
    deleteBeans(CpoQuery query, List<T> beans)
    Removes the beans from the datasource using the query's DELETE function group, batching where the datasource supports it.
    default <T> T
    executeBean(String groupName, T bean)
    Executes the named EXECUTE function group with the bean as both criteria and result.
    <T, C> T
    executeBean(CpoQuery query, C criteria, T result)
    Executes the EXECUTE function group identified by the query — typically a stored procedure — using the criteria bean to populate the IN arguments and the result bean type for the OUT arguments.
    default <T> T
    executeBean(T bean)
    Executes the default EXECUTE function group with the bean as both criteria and result.
    default <T> long
    existsBean(String groupName, T bean)
    Checks whether beans matching the given bean exist, using the named EXIST function group.
    <T> long
    existsBean(CpoQuery query, T bean)
    Checks whether beans matching the given bean exist in the datasource, using the query's EXIST function group and where constraints.
    default <T> long
    existsBean(T bean)
    Checks whether beans matching the given bean exist, using the default EXIST function group.
    int
    getBatchSize()
    Get the batch size for updating the datasource
    List<CpoAttribute>
    getCpoAttributes(String expression)
    Gets the CpoAttribute definitions matching a comma-separated expression of attribute names, as declared in the meta data for this bean's class.
    CpoMetaDescriptor
    getCpoMetaDescriptor()
    Get the CpoMetaDescriptor
    String
    getDataSourceName()
    Get the name of the datasource
    int
    getFetchSize()
    Get the fetch size for the datasource
    default <T> long
    insertBean(String groupName, T bean)
    Creates the bean in the datasource using the named CREATE function group.
    <T> long
    insertBean(CpoQuery query, T bean)
    Creates the bean in the datasource using the query's CREATE function group.
    default <T> long
    insertBean(T bean)
    Creates the bean in the datasource using the default CREATE function group.
    default <T> long
    insertBeans(String groupName, List<T> beans)
    Creates the beans in the datasource using the named CREATE function group.
    default <T> long
    insertBeans(List<T> beans)
    Creates the beans in the datasource using the default CREATE function group.
    <T> long
    insertBeans(CpoQuery query, List<T> beans)
    Creates the beans in the datasource using the query's CREATE function group, batching where the datasource supports it.
    CpoOrderBy
    newOrderBy(String attribute, boolean ascending)
    Creates a CpoOrderBy for the attribute and direction.
    CpoOrderBy
    newOrderBy(String attribute, boolean ascending, String function)
    Creates a CpoOrderBy applying a datasource function to the attribute.
    CpoOrderBy
    newOrderBy(String marker, String attribute, boolean ascending)
    Creates a CpoOrderBy bound to a marker within the expression.
    CpoOrderBy
    newOrderBy(String marker, String attribute, boolean ascending, String function)
    Creates a CpoOrderBy bound to a marker, applying a datasource function to the attribute.
    CpoWhere
    newWhere()
    Creates an empty CpoWhere.
    <T> CpoWhere
    newWhere(Logical logical, String attr, Comparison comp, T value)
    Creates a CpoWhere comparing the attribute to the value.
    <T> CpoWhere
    newWhere(Logical logical, String attr, Comparison comp, T value, boolean not)
    Creates a CpoWhere comparing the attribute to the value, optionally negated.
    default <T> T
    retrieveBean(String groupName, T bean)
    Retrieves a single bean using the named RETRIEVE function group; the bean supplies the search criteria and receives the result.
    <T, C> T
    retrieveBean(CpoQuery query, C criteria, T result)
    Retrieves the first bean produced by the query's RETRIEVE function group, using separate criteria and result beans.
    <T> T
    retrieveBean(CpoQuery query, T bean)
    Retrieves a single bean from the datasource using the query's RETRIEVE function group, with the given bean supplying the search criteria and receiving the result.
    default <T> T
    retrieveBean(T bean)
    Retrieves a single bean using the default RETRIEVE function group; the bean supplies the search criteria and receives the result.
    default <C> Stream<C>
    retrieveBeans(String groupName, C criteria)
    Retrieves beans using the named LIST function group; the criteria bean type is also the result type.
    default <T, C> Stream<T>
    retrieveBeans(String groupName, C criteria, T result)
    Retrieves beans using the named LIST function group with separate criteria and result beans.
    default <C> Stream<C>
    retrieveBeans(CpoQuery query, C criteria)
    Retrieves beans from the datasource using the query's LIST function group; the criteria bean type is also the result type.
    <T, C> Stream<T>
    retrieveBeans(CpoQuery query, C criteria, T result)
    Retrieves beans from the datasource using the query's LIST function group, with separate criteria and result beans.
    void
    setBatchSize(int batchsize)
    set the batch size for updating the datasource
    void
    setFetchSize(int fetchSize)
    set the fetch size for the datasource
    default <T> long
    updateBean(String groupName, T bean)
    Updates the bean in the datasource using the named UPDATE function group.
    <T> long
    updateBean(CpoQuery query, T bean)
    Updates the bean in the datasource using the query's UPDATE function group.
    default <T> long
    updateBean(T bean)
    Updates the bean in the datasource using the default UPDATE function group.
    default <T> long
    updateBeans(String groupName, List<T> beans)
    Updates the beans in the datasource using the named UPDATE function group.
    default <T> long
    updateBeans(List<T> beans)
    Updates the beans in the datasource using the default UPDATE function group.
    <T> long
    updateBeans(CpoQuery query, List<T> beans)
    Updates the beans in the datasource using the query's UPDATE function group, batching where the datasource supports it.
    default <T> long
    upsertBean(String groupName, T bean)
    Inserts or updates the bean using the named UPSERT function group.
    <T> long
    upsertBean(CpoQuery query, T bean)
    Inserts or updates the bean using the query's UPSERT function group: the EXIST function decides whether the CREATE or UPDATE function is executed.
    default <T> long
    upsertBean(T bean)
    Inserts or updates the bean using the default UPSERT function group.
    default <T> long
    upsertBeans(String groupName, List<T> beans)
    Inserts or updates the beans using the named UPSERT function group.
    default <T> long
    upsertBeans(List<T> beans)
    Inserts or updates the beans using the default UPSERT function group.
    <T> long
    upsertBeans(CpoQuery query, List<T> beans)
    Inserts or updates the beans using the query's UPSERT function group: for each bean the EXIST function decides whether the CREATE or UPDATE function is executed.

  • Method Details

    • insertBean

      <T> long insertBean(CpoQuery query, T bean) throws CpoException
      Creates the bean in the datasource using the query's CREATE function group. The assumption is that the bean does not exist in the datasource. 
      
 SomeBean bean = new SomeBean();
 bean.setId(1);
 bean.setName("SomeName");
 cpo.insertBean(CpoQuery.group("createBean"), bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans created in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • insertBeans

      <T> long insertBeans(CpoQuery query, List<T> beans) throws CpoException
      Creates the beans in the datasource using the query's CREATE function group, batching where the datasource supports it. This is an all-or-nothing transaction: if one bean fails, no beans are created. 
      
 List<SomeBean> beans = List.of(bean1, bean2);
 long created = cpo.insertBeans(CpoQuery.group("createBean"), beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      beans - The beans to create
      Returns:
      The number of beans created in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • insertBean

      default <T> long insertBean(T bean) throws CpoException
      Creates the bean in the datasource using the default CREATE function group. 
      
 cpo.insertBean(bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans created in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • insertBean

      default <T> long insertBean(String groupName, T bean) throws CpoException
      Creates the bean in the datasource using the named CREATE function group. 
      
 cpo.insertBean("createBean", bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The CREATE function group name; null signifies the default group
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans created in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • insertBeans

      default <T> long insertBeans(List<T> beans) throws CpoException
      Creates the beans in the datasource using the default CREATE function group. 
      
 cpo.insertBeans(beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      beans - The beans to create
      Returns:
      The number of beans created in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • insertBeans

      default <T> long insertBeans(String groupName, List<T> beans) throws CpoException
      Creates the beans in the datasource using the named CREATE function group. 
      
 cpo.insertBeans("createBean", beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The CREATE function group name; null signifies the default group
      beans - The beans to create
      Returns:
      The number of beans created in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • deleteBean

      <T> long deleteBean(CpoQuery query, T bean) throws CpoException
      Removes the bean from the datasource using the query's DELETE function group. The assumption is that the bean exists in the datasource. 
      
 SomeBean bean = new SomeBean();
 bean.setId(1);
 cpo.deleteBean(CpoQuery.group("deleteBean"), bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans deleted from the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • deleteBeans

      <T> long deleteBeans(CpoQuery query, List<T> beans) throws CpoException
      Removes the beans from the datasource using the query's DELETE function group, batching where the datasource supports it. This is an all-or-nothing transaction: if one bean fails, no beans are deleted. 
      
 long deleted = cpo.deleteBeans(CpoQuery.group("deleteBean"), beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      beans - The beans to delete
      Returns:
      The number of beans deleted from the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • deleteBean

      default <T> long deleteBean(T bean) throws CpoException
      Removes the bean from the datasource using the default DELETE function group. 
      
 cpo.deleteBean(bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans deleted from the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • deleteBean

      default <T> long deleteBean(String groupName, T bean) throws CpoException
      Removes the bean from the datasource using the named DELETE function group. 
      
 cpo.deleteBean("deleteBean", bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The DELETE function group name; null signifies the default group
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans deleted from the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • deleteBeans

      default <T> long deleteBeans(List<T> beans) throws CpoException
      Removes the beans from the datasource using the default DELETE function group. 
      
 cpo.deleteBeans(beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      beans - The beans to delete
      Returns:
      The number of beans deleted from the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • deleteBeans

      default <T> long deleteBeans(String groupName, List<T> beans) throws CpoException
      Removes the beans from the datasource using the named DELETE function group. 
      
 cpo.deleteBeans("deleteBean", beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The DELETE function group name; null signifies the default group
      beans - The beans to delete
      Returns:
      The number of beans deleted from the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • updateBean

      <T> long updateBean(CpoQuery query, T bean) throws CpoException
      Updates the bean in the datasource using the query's UPDATE function group. The assumption is that the bean exists in the datasource. 
      
 SomeBean bean = new SomeBean();
 bean.setId(1);
 bean.setName("NewName");
 cpo.updateBean(CpoQuery.group("updateBean"), bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans updated in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • updateBeans

      <T> long updateBeans(CpoQuery query, List<T> beans) throws CpoException
      Updates the beans in the datasource using the query's UPDATE function group, batching where the datasource supports it. This is an all-or-nothing transaction: if one bean fails, no beans are updated. 
      
 long updated = cpo.updateBeans(CpoQuery.group("updateBean"), beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      beans - The beans to update
      Returns:
      The number of beans updated in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • updateBean

      default <T> long updateBean(T bean) throws CpoException
      Updates the bean in the datasource using the default UPDATE function group. 
      
 cpo.updateBean(bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans updated in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • updateBean

      default <T> long updateBean(String groupName, T bean) throws CpoException
      Updates the bean in the datasource using the named UPDATE function group. 
      
 cpo.updateBean("updateBean", bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The UPDATE function group name; null signifies the default group
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans updated in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • updateBeans

      default <T> long updateBeans(List<T> beans) throws CpoException
      Updates the beans in the datasource using the default UPDATE function group. 
      
 cpo.updateBeans(beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      beans - The beans to update
      Returns:
      The number of beans updated in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • updateBeans

      default <T> long updateBeans(String groupName, List<T> beans) throws CpoException
      Updates the beans in the datasource using the named UPDATE function group. 
      
 cpo.updateBeans("updateBean", beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The UPDATE function group name; null signifies the default group
      beans - The beans to update
      Returns:
      The number of beans updated in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • upsertBean

      <T> long upsertBean(CpoQuery query, T bean) throws CpoException
      Inserts or updates the bean using the query's UPSERT function group: the EXIST function decides whether the CREATE or UPDATE function is executed. 
      
 SomeBean bean = new SomeBean();
 bean.setId(1);
 bean.setName("SomeName");
 cpo.upsertBean(CpoQuery.group("upsertBean"), bean); // inserts or updates as needed
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans upserted in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource, or if the EXIST function matches more than one record

    • upsertBeans

      <T> long upsertBeans(CpoQuery query, List<T> beans) throws CpoException
      Inserts or updates the beans using the query's UPSERT function group: for each bean the EXIST function decides whether the CREATE or UPDATE function is executed. 
      
 long upserted = cpo.upsertBeans(CpoQuery.group("upsertBean"), beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      beans - The beans to upsert
      Returns:
      The number of beans upserted in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource, or if the EXIST function matches more than one record

    • upsertBean

      default <T> long upsertBean(T bean) throws CpoException
      Inserts or updates the bean using the default UPSERT function group. 
      
 cpo.upsertBean(bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans upserted in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource, or if the EXIST function matches more than one record

    • upsertBean

      default <T> long upsertBean(String groupName, T bean) throws CpoException
      Inserts or updates the bean using the named UPSERT function group. 
      
 cpo.upsertBean("upsertBean", bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The UPSERT function group name; null signifies the default group
      bean - A bean defined within the metadata of the datasource
      Returns:
      The number of beans upserted in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource, or if the EXIST function matches more than one record

    • upsertBeans

      default <T> long upsertBeans(List<T> beans) throws CpoException
      Inserts or updates the beans using the default UPSERT function group. 
      
 cpo.upsertBeans(beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      beans - The beans to upsert
      Returns:
      The number of beans upserted in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource, or if the EXIST function matches more than one record

    • upsertBeans

      default <T> long upsertBeans(String groupName, List<T> beans) throws CpoException
      Inserts or updates the beans using the named UPSERT function group. 
      
 cpo.upsertBeans("upsertBean", beans);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The UPSERT function group name; null signifies the default group
      beans - The beans to upsert
      Returns:
      The number of beans upserted in the datasource
      Throws:
      CpoException - Thrown if there are errors accessing the datasource, or if the EXIST function matches more than one record

    • existsBean

      <T> long existsBean(CpoQuery query, T bean) throws CpoException
      Checks whether beans matching the given bean exist in the datasource, using the query's EXIST function group and where constraints. 
      
 CpoWhere where = cpo.newWhere(Logical.NONE, "id", Comparison.EQ, 1);
 long count = cpo.existsBean(CpoQuery.group("existsBean").where(where), bean);
 if (count > 0) {
   // the bean exists
 }
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      bean - The bean to search for in the datasource
      Returns:
      The number of beans that exist in the datasource that match the specified bean. An EXIST function must either return a count as a single row with a single numeric column (count(*) style) or return one row per matching bean; a single-row result with one numeric column is always interpreted as a count
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • existsBean

      default <T> long existsBean(T bean) throws CpoException
      Checks whether beans matching the given bean exist, using the default EXIST function group. 
      
 long count = cpo.existsBean(bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - The bean to search for in the datasource
      Returns:
      The number of beans that exist in the datasource that match the specified bean
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • existsBean

      default <T> long existsBean(String groupName, T bean) throws CpoException
      Checks whether beans matching the given bean exist, using the named EXIST function group. 
      
 long count = cpo.existsBean("existsBean", bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The EXIST function group name; null signifies the default group
      bean - The bean to search for in the datasource
      Returns:
      The number of beans that exist in the datasource that match the specified bean
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • executeBean

      <T, C> T executeBean(CpoQuery query, C criteria, T result) throws CpoException
      Executes the EXECUTE function group identified by the query — typically a stored procedure — using the criteria bean to populate the IN arguments and the result bean type for the OUT arguments. 
      
 SomeResult result =
     cpo.executeBean(CpoQuery.group("calculateTotals"), criteria, new SomeResult());
      Type Parameters:
      T - The type of the result JavaBean
      C - The type of the criteria JavaBean
      Parameters:
      query - The function group to execute
      criteria - A bean defined within the metadata of the datasource used to populate the IN arguments
      result - A bean defined within the metadata of the datasource that defines the bean type populated with the OUT arguments
      Returns:
      A result bean populated with the OUT arguments
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • executeBean

      default <T> T executeBean(T bean) throws CpoException
      Executes the default EXECUTE function group with the bean as both criteria and result. 
      
 SomeBean result = cpo.executeBean(bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - The bean used for the IN arguments and populated with the OUT arguments
      Returns:
      A result bean populated with the OUT arguments
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • executeBean

      default <T> T executeBean(String groupName, T bean) throws CpoException
      Executes the named EXECUTE function group with the bean as both criteria and result. 
      
 SomeBean result = cpo.executeBean("calculateTotals", bean);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The EXECUTE function group name; null signifies the default group
      bean - The bean used for the IN arguments and populated with the OUT arguments
      Returns:
      A result bean populated with the OUT arguments
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • retrieveBean

      <T> T retrieveBean(CpoQuery query, T bean) throws CpoException
      Retrieves a single bean from the datasource using the query's RETRIEVE function group, with the given bean supplying the search criteria and receiving the result. If the function returns more than one row, an exception is thrown. 
      
 SomeBean criteria = new SomeBean();
 criteria.setId(1);
 SomeBean bean = cpo.retrieveBean(CpoQuery.group("retrieveBean"), criteria);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      query - The function group and clauses to apply
      bean - A bean defined within the metadata of the datasource whose attributes supply the search criteria
      Returns:
      A populated bean of the same type as the bean passed in, or null if no beans match
      Throws:
      CpoException - Thrown if there are errors accessing the datasource or more than one row is returned

    • retrieveBean

      <T, C> T retrieveBean(CpoQuery query, C criteria, T result) throws CpoException
      Retrieves the first bean produced by the query's RETRIEVE function group, using separate criteria and result beans. 
      
 SomeResult result =
     cpo.retrieveBean(CpoQuery.group("retrieveResult"), criteria, new SomeResult());
      Type Parameters:
      T - The type of the result JavaBean
      C - The type of the criteria JavaBean
      Parameters:
      query - The function group and clauses to apply
      criteria - A bean defined within the metadata of the datasource that supplies the retrieval parameters
      result - A bean defined within the metadata of the datasource that specifies the returned bean type
      Returns:
      A bean of the same type as the result parameter, or null if no beans match
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • retrieveBean

      default <T> T retrieveBean(T bean) throws CpoException
      Retrieves a single bean using the default RETRIEVE function group; the bean supplies the search criteria and receives the result. 
      
 SomeBean bean = cpo.retrieveBean(criteria);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      bean - A bean defined within the metadata of the datasource whose attributes supply the search criteria
      Returns:
      A populated bean of the same type as the bean passed in, or null if no beans match
      Throws:
      CpoException - Thrown if there are errors accessing the datasource or more than one row is returned

    • retrieveBean

      default <T> T retrieveBean(String groupName, T bean) throws CpoException
      Retrieves a single bean using the named RETRIEVE function group; the bean supplies the search criteria and receives the result. 
      
 SomeBean bean = cpo.retrieveBean("retrieveBean", criteria);
      Type Parameters:
      T - The type of the JavaBean
      Parameters:
      groupName - The RETRIEVE function group name; null signifies the default group
      bean - A bean defined within the metadata of the datasource whose attributes supply the search criteria
      Returns:
      A populated bean of the same type as the bean passed in, or null if no beans match
      Throws:
      CpoException - Thrown if there are errors accessing the datasource or more than one row is returned

    • retrieveBeans

      <T, C> Stream<T> retrieveBeans(CpoQuery query, C criteria, T result) throws CpoException
      Retrieves beans from the datasource using the query's LIST function group, with separate criteria and result beans. 
      
 CpoWhere where = cpo.newWhere(Logical.NONE, "dept", Comparison.EQ, "sales");
 CpoOrderBy orderBy = cpo.newOrderBy("name", true);
 try (Stream<SomeResult> beans =
     cpo.retrieveBeans(
         CpoQuery.group("listResults").where(where).orderBy(orderBy),
         criteria,
         new SomeResult())) {
   beans.forEach(...);
 }
      Type Parameters:
      T - The type of the result JavaBean
      C - The type of the criteria JavaBean
      Parameters:
      query - The function group and clauses to apply
      criteria - A bean defined within the metadata of the datasource that supplies the retrieval parameters
      result - A bean defined within the metadata of the datasource that specifies the returned bean type
      Returns:
      A stream of beans that meet the criteria; empty if none match. The stream is backed by open datastore resources (statement, result set, and connection) that are released only when the stream is closed; terminal operations do not close it. Always close the returned stream, preferably with try-with-resources.
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • retrieveBeans

      default <C> Stream<C> retrieveBeans(CpoQuery query, C criteria) throws CpoException
      Retrieves beans from the datasource using the query's LIST function group; the criteria bean type is also the result type. 
      
 CpoWhere where = cpo.newWhere(Logical.NONE, "dept", Comparison.EQ, "sales");
 try (Stream<SomeBean> beans =
     cpo.retrieveBeans(CpoQuery.group("listBeans").where(where), criteria)) {
   beans.forEach(...);
 }
      Type Parameters:
      C - The type of the criteria JavaBean
      Parameters:
      query - The function group and clauses to apply
      criteria - A bean defined within the metadata of the datasource that supplies the retrieval parameters
      Returns:
      A stream of beans that meet the criteria; empty if none match. The stream is backed by open datastore resources (statement, result set, and connection) that are released only when the stream is closed; terminal operations do not close it. Always close the returned stream, preferably with try-with-resources.
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • retrieveBeans

      default <C> Stream<C> retrieveBeans(String groupName, C criteria) throws CpoException
      Retrieves beans using the named LIST function group; the criteria bean type is also the result type. 
      
 try (Stream<SomeBean> beans = cpo.retrieveBeans("listBeans", criteria)) {
   beans.forEach(...);
 }
      Type Parameters:
      C - The type of the criteria JavaBean
      Parameters:
      groupName - The LIST function group name; null signifies the default group
      criteria - A bean defined within the metadata of the datasource that supplies the retrieval parameters
      Returns:
      A stream of beans that meet the criteria; empty if none match. Always close the returned stream, preferably with try-with-resources.
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • retrieveBeans

      default <T, C> Stream<T> retrieveBeans(String groupName, C criteria, T result) throws CpoException
      Retrieves beans using the named LIST function group with separate criteria and result beans. 
      
 try (Stream<SomeResult> beans =
     cpo.retrieveBeans("listResults", criteria, new SomeResult())) {
   beans.forEach(...);
 }
      Type Parameters:
      T - The type of the result JavaBean
      C - The type of the criteria JavaBean
      Parameters:
      groupName - The LIST function group name; null signifies the default group
      criteria - A bean defined within the metadata of the datasource that supplies the retrieval parameters
      result - A bean defined within the metadata of the datasource that specifies the returned bean type
      Returns:
      A stream of beans that meet the criteria; empty if none match. Always close the returned stream, preferably with try-with-resources.
      Throws:
      CpoException - Thrown if there are errors accessing the datasource

    • newOrderBy

      CpoOrderBy newOrderBy(String attribute, boolean ascending) throws CpoException
      Creates a CpoOrderBy for the attribute and direction. 
      
 CpoOrderBy byNameAscending = cpo.newOrderBy("name", true);
      Parameters:
      attribute - The metadata attribute name to order by
      ascending - true for ascending, false for descending
      Returns:
      A CpoOrderBy
      Throws:
      CpoException - An error occurred creating the CpoOrderBy

    • newOrderBy

      CpoOrderBy newOrderBy(String marker, String attribute, boolean ascending) throws CpoException
      Creates a CpoOrderBy bound to a marker within the expression.
      Parameters:
      marker - The marker in the expression that this order-by replaces
      attribute - The metadata attribute name to order by
      ascending - true for ascending, false for descending
      Returns:
      A CpoOrderBy
      Throws:
      CpoException - An error occurred creating the CpoOrderBy

    • newOrderBy

      CpoOrderBy newOrderBy(String attribute, boolean ascending, String function) throws CpoException
      Creates a CpoOrderBy applying a datasource function to the attribute.
      Parameters:
      attribute - The metadata attribute name to order by
      ascending - true for ascending, false for descending
      function - A datasource function to apply to the attribute
      Returns:
      A CpoOrderBy
      Throws:
      CpoException - An error occurred creating the CpoOrderBy

    • newOrderBy

      CpoOrderBy newOrderBy(String marker, String attribute, boolean ascending, String function) throws CpoException
      Creates a CpoOrderBy bound to a marker, applying a datasource function to the attribute.
      Parameters:
      marker - The marker in the expression that this order-by replaces
      attribute - The metadata attribute name to order by
      ascending - true for ascending, false for descending
      function - A datasource function to apply to the attribute
      Returns:
      A CpoOrderBy
      Throws:
      CpoException - An error occurred creating the CpoOrderBy

    • newWhere

      CpoWhere newWhere() throws CpoException
      Creates an empty CpoWhere. 
      
 CpoWhere where = cpo.newWhere();
      Returns:
      A CpoWhere
      Throws:
      CpoException - An error occurred creating the CpoWhere

    • newWhere

      <T> CpoWhere newWhere(Logical logical, String attr, Comparison comp, T value) throws CpoException
      Creates a CpoWhere comparing the attribute to the value. 
      
 CpoWhere where = cpo.newWhere(Logical.NONE, "id", Comparison.EQ, 42);
      Type Parameters:
      T - The type of the value
      Parameters:
      logical - How this where combines with the preceding where (AND, OR, NONE)
      attr - The metadata attribute name to constrain
      comp - The comparison operator
      value - The value to compare against
      Returns:
      A CpoWhere
      Throws:
      CpoException - An error occurred creating the CpoWhere

    • newWhere

      <T> CpoWhere newWhere(Logical logical, String attr, Comparison comp, T value, boolean not) throws CpoException
      Creates a CpoWhere comparing the attribute to the value, optionally negated.
      Type Parameters:
      T - The type of the value
      Parameters:
      logical - How this where combines with the preceding where (AND, OR, NONE)
      attr - The metadata attribute name to constrain
      comp - The comparison operator
      value - The value to compare against
      not - true to negate the comparison
      Returns:
      A CpoWhere
      Throws:
      CpoException - An error occurred creating the CpoWhere

    • getCpoMetaDescriptor

      CpoMetaDescriptor getCpoMetaDescriptor()
      Get the CpoMetaDescriptor
      Returns:
      The CpoMetaDescriptor

    • getDataSourceName

      String getDataSourceName()
      Get the name of the datasource
      Returns:
      The name of the datasource

    • getFetchSize

      int getFetchSize()
      Get the fetch size for the datasource
      Returns:
      The fetchsize

    • setFetchSize

      void setFetchSize(int fetchSize)
      set the fetch size for the datasource
      Parameters:
      fetchSize - The fetchsize to set for retrieving data

    • getBatchSize

      int getBatchSize()
      Get the batch size for updating the datasource
      Returns:
      The batchsize

    • setBatchSize

      void setBatchSize(int batchsize)
      set the batch size for updating the datasource
      Parameters:
      batchsize - The batchsize for updating the datasource

    • getCpoAttributes

      List<CpoAttribute> getCpoAttributes(String expression) throws CpoException
      Gets the CpoAttribute definitions matching a comma-separated expression of attribute names, as declared in the meta data for this bean's class.
      Parameters:
      expression - An expression defining the CpoAttributes that you want
      Returns:
      A list of CpoAttributes
      Throws:
      CpoException - Thrown if there are errors accessing the datasource