View Javadoc

    1   package org.example.customerdao;
    2
    3   /*
    4    * This is free and unencumbered software released into the public domain.
    5    * Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software,
    6    * either in source code form or as a compiled binary, for any purpose, commercial or
    7    * non-commercial, and by any means.
    8    *
    9    * In jurisdictions that recognize copyright laws, the author or authors of this
    10   * software dedicate any and all copyright interest in the software to the public domain.
    11   * We make this dedication for the benefit of the public at large and to the detriment of
    12   * our heirs and successors. We intend this dedication to be an overt act of relinquishment in
    13   * perpetuity of all present and future rights to this software under copyright law.
    14   *
    15   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
    16   * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
    17   * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES
    18   * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    19   * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    20   *
    21   * For more information, please refer to: https://unlicense.org/
    22  */
    23
    24  import java.util.List;
    25
    26  import javax.sql.DataSource;
    27
    28  import org.example.customer.Customer;
    29  import org.example.customerdao.utility.Deleteable;
    30  import org.example.websecurity.UserCredentials;
    31
    32  /**
    33   * This is the CustomerDAO Interface for the Customer DAO component of the Customer Web Application.
    34   * This will be the primary Customer database exposure for the Customer Web Layer.
    35   *
    36   * @author Jonathan Earl
    37   * @since 1.0
    38   *
    39   */
    40  public interface CustomerDAO extends Deleteable
    41  {
    42      /**
    43       * Sets the Read Only DataSource for this DAO Implication.
    44       *
    45       * @param readOnlyDS the readOnlyDS to set
    46       */
    47      void setReadOnlyDS(DataSource readOnlyDS);
    48
    49
    50      /**
    51       * Sets the Read/Write DataSource for this DAO Implication.
    52       *
    53       * @param readWriteOnlyDS the readWriteOnlyDS to set
    54       */
    55      void setReadWriteDS(DataSource readWriteOnlyDS);
    56
    57      /**
    58       * Finds all Customers.
    59       *
    60       * @param credentials the UserCredentials for this Database operation
    61       * @return a list of Customers, this list may be empty
    62       * @throws IllegalArgumentException
    63       *              if there is a connection or permission problem
    64       */
    65      List<Customer> findAllCustomers(UserCredentials credentials);
    66
    67      /**
    68       * Find Customer by Id.
    69       * <p>
    70       * This will return null if the Customer cannot be found.
    71       *
    72       * @param credentials the UserCredentials for this Database operation
    73       * @param id the Customer ID to search for
    74       * @return a Customer or null if the Customer is not found
    75       * @throws IllegalArgumentException
    76       *              if there is a connection or permission problem
    77       */
    78      Customer findCustomerById(UserCredentials credentials, int id);
    79
    80      /**
    81       * Find Customers by Name.
    82       *
    83       * @param credentials the UserCredentials for this Database operation
    84       * @param firstName the first name to search for
    85       * @param lastName the last name to search for
    86       * @return a list of Customers, this list may be empty
    87       * @throws IllegalArgumentException
    88       *              if there is a connection or permission problem
    89       */
    90      List<Customer> findCustomersByName(UserCredentials credentials, String firstName, String lastName);
    91
    92      /**
    93       * Adds a Customer.
    94       * <p >
    95       * Only a Manager is permitted to add a Customer.
    96       *
    97       *
    98       * @param credentials the UserCredentials for this Database operation
    99       * @param customer the Customer object to add
    100      * @return the id of the new Customer record
    101      * @throws IllegalArgumentException
    102      *              if there is a connection or permission problem
    103      */
    104     int addCustomer(UserCredentials credentials, Customer customer);
    105
    106     /**
    107      * Updates a Customer.
    108      * <p >
    109      * Only a Manager is permitted to update a Customer.
    110      *
    111      *
    112      * @param credentials the UserCredentials for this Database operation
    113      * @param customer the Customer object to update
    114      * @throws IllegalArgumentException
    115      *              if there is a connection or permission problem
    116      */
    117     void updateCustomer(UserCredentials credentials, Customer customer);
    118 }