DataQueryInterface


1   /* ====================================================================
2    * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002
3    *
4    * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved.
5    *
6    * Redistribution and use in source and binary forms, with or without
7    * modification, are permitted provided that the following conditions
8    * are met:
9    *
10   * 1. Redistributions of source code must retain the above copyright
11   *    notice, this list of conditions and the following disclaimer.
12   *
13   * 2. Redistributions in binary form must reproduce the above copyright
14   *    notice, this list of conditions and the following disclaimer in
15   *    the documentation and/or other materials provided with the
16   *    distribution.
17   *
18   * 3. The end-user documentation included with the redistribution,
19   *    if any, must include the following acknowledgment:
20   *       "This product includes software developed by Jcorporate Ltd.
21   *        (http://www.jcorporate.com/)."
22   *    Alternately, this acknowledgment may appear in the software itself,
23   *    if and wherever such third-party acknowledgments normally appear.
24   *
25   * 4. "Jcorporate" and product names such as "Expresso" must
26   *    not be used to endorse or promote products derived from this
27   *    software without prior written permission. For written permission,
28   *    please contact info@jcorporate.com.
29   *
30   * 5. Products derived from this software may not be called "Expresso",
31   *    or other Jcorporate product names; nor may "Expresso" or other
32   *    Jcorporate product names appear in their name, without prior
33   *    written permission of Jcorporate Ltd.
34   *
35   * 6. No product derived from this software may compete in the same
36   *    market space, i.e. framework, without prior written permission
37   *    of Jcorporate Ltd. For written permission, please contact
38   *    partners@jcorporate.com.
39   *
40   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
41   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
42   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
43   * DISCLAIMED.  IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS
44   * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
45   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
46   * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
47   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
48   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
49   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
50   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
51   * SUCH DAMAGE.
52   * ====================================================================
53   *
54   * This software consists of voluntary contributions made by many
55   * individuals on behalf of the Jcorporate Ltd. Contributions back
56   * to the project(s) are encouraged when you make modifications.
57   * Please send them to support@jcorporate.com. For more information
58   * on Jcorporate Ltd. and its products, please see
59   * <http://www.jcorporate.com/>.
60   *
61   * Portions of this software are based upon other open source
62   * products and are subject to their respective licenses.
63   */
64  
65  package com.jcorporate.expresso.core.dataobjects;
66  
67  import java.util.List  ;
68  
69  /**
70   * This interface provides a standard interface to deal with parts that
71   * operate and return multiple DataObjects.  This is in an attempt to make a
72   * DataObject more focused than before. [ie to cut down on size] by separating
73   * operations on a single dbobject from operations on a multiple dbobject.
74   *
75   * @author Michael Rimov
76   * @since Expresso 5.0
77   */
78  public interface DataQueryInterface {
79  
80      /**
81       * Performs a datasource search so that the criteria set in the DataObject
82       * is used.
83       *
84       * @param criteria  a <code>DataObject</code> with the fields filled out so that
85       *                  all objects returned will match the fields specified in the <code>DataObject</code>
86       * @param sortOrder A pipe delimited string specifying the field(s) to be sorted upon.
87       *                  May be a single field without any pipes.
88       * @return <code>java.util.List</code> of objects.  May be an empty list if no
89       *         objects were found.
90       * @throws DataException upon error performing the search
91       */
92      public List   searchAndRetrieve(DataObject criteria, String   sortOrder) throws DataException;
93  
94      /**
95       * Performs a datasource search so that the criteria set in the DataObject
96       * is used.  There is no specified sort order for this version of the method
97       *
98       * @param criteria a <code>DataObject</code> with the fields filled out so that
99       *                 all objects returned will match the fields specified in the <code>DataObject</code>
100      * @return <code>java.util.List</code> of objects.  May be an empty list if no
101      *         objects were found.
102      * @throws DataException upon error performing the search
103      */
104     public List   searchAndRetrieve(DataObject criteria) throws DataException;
105 
106     /**
107      * Performs a datasource search so that the criteria set by a <code>DataTransferObject</code>
108      * is used.  This is different from the DataObject search in that it is often meant
109      * to be used on remote machines where serializing lots of DataObjects is more expensive.  Since
110      * a typical DataTransferObject is 1/2 the size of a DataObject, we significantly reduce
111      * network traffic by using this method at the expense of CPU time to translate the <code>DataTransferObject</code>
112      * back into a <code>DataObject</code>
113      *
114      * @param criteria a <code>DataTransferObject</code> with the fields filled out so that
115      *                 all objects returned will match the fields specified in the <code>DataTransferObject</code>
116      * @return <code>java.util.List</code> of <code>DataTransferObject</code>.  May be an empty list if no
117      *         objects were found.
118      * @throws DataException upon error performing the search
119      */
120     public List   searchAndRetrieve(DataTransferObject criteria) throws DataException;
121 
122     /**
123      * Performs a datasource search so that the criteria set by a <code>DataTransferObject</code>
124      * is used. This is different from the DataObject search in that it is often meant
125      * to be used on remote machines where serializing lots of DataObjects is more expensive.  Since
126      * a typical DataTransferObject is 1/2 the size of a DataObject, we significantly reduce
127      * network traffic by using this method at the expense of CPU time to translate the <code>DataTransferObject</code>
128      * back into a <code>DataObject</code>
129      *
130      * @param criteria  a <code>DataTransferObject</code> with the fields filled out so that
131      *                  all objects returned will match the fields specified in the <code>DataTransferObject</code>
132      * @param sortOrder A pipe delimited string specifying the field(s) to be sorted upon.
133      *                  May be a single field without any pipes.
134      * @return <code>java.util.List</code> of <code>DataTransferObject</code>.  May be an empty list if no
135      *         objects were found.
136      * @throws DataException upon error performing the search
137      */
138     public List   searchAndRetrieve(DataTransferObject criteria, String   sortOrder) throws DataException;
139 
140     /**
141      * Finds a single record based upon the criteria specified by the <code>DataObject</code>
142      *
143      * @param criteria a <code>DataObject</code> with the fields to match filled out.
144      * @return boolean true if a record was found, and the <i>criteria</i> parameter
145      *         is filled with the first data object found.
146      * @throws DataException upon error performing the search
147      */
148     public boolean find(DataObject criteria) throws DataException;
149 
150 
151     /**
152      * Finds a single record based upon the criteria specified by the <code>DataTransferObject</code>
153      *
154      * @param criteria a <code>DataTransferObject</code> with the fields to match filled out.
155      * @return boolean true if a record was found, and the <i>criteria</i> parameter
156      *         is filled with the first data object found.
157      * @throws DataException upon error performing the search
158      */
159     public boolean find(DataTransferObject criteria) throws DataException;
160 
161 
162     /**
163      * Release the query and all connections/resources associated with the
164      * query.
165      */
166     public void release();
167 
168 }
169
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags