RetrieveDesc


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  /*
25   * RetrieveDesc.java
26   *
27   * Created on March 3, 2000
28   */
29  
30  package com.sun.jdo.spi.persistence.support.sqlstore;
31  
32  
33  /**
34   * <P>This interface represents a retrieve descriptor used by an application
35   * to retrieve container-managed entity beans from a persistent store. It
36   * allows you specify which persistent fields an application wants to retrieve.
37   * In addition, it allows an application to specify sophisticated constraints
38   * on its object retrieval.
39   */
40  public interface RetrieveDesc extends ActionDesc {
41  
42      /**
43      * The addResult method is used to specify which fields should be
44      * returned in a persistent object. If the field requested is a
45      * reference to another persistent object then a RetrieveDesc may be
46      * provided which describes which fields of the referenced object
47      * should be returned and, optionally, constraints on it.
48      * The parameter <code>projection</code> specifies, if the field
49      * specified by <code>name</code> should be projected.
50      *
51      * @param name The name of the field to return.
52      * @param foreignConstraint
53      * RetrieveDesc describing fields and constraints for a referenced object.
54      * @param projection Specifies, if this is a projection.
55      */
56     public void addResult(String   name, RetrieveDesc foreignConstraint, boolean projection);
57  
58      /**
59       * The addResult method can be used to specify <it>global</it>
60       * query attributes that don't end up in the where clause.
61       * Aggregate functions and the distinct op code are examples for
62       * those query options. The result type defines the object to be
63       * returned by an aggregate query. In case of distinct the result
64       * type should be FieldTypeEnumeration.NOT_ENUMERATED. The method
65       * might be called twice, in case of a JDOQL query having both an
66       * aggregate and distinct:
67       * query.setResult("avg (distinct salary)");
68       * ->
69       * retrieveDesc.addResult(OP_AVG, FieldTypeEnumeration.DOUBLE);
70       * retrieveDesc.addResult(OP_DISTINCT, FieldTypeEnumeration.NOT_ENUMERATED);
71       * retrieveDesc.addResult("salary", null, true);
72       *
73       * @param opCode The operation code.
74       * @param resultType The object type returned by aggregate queries.
75       * @see com.sun.jdo.spi.persistence.utility.FieldTypeEnumeration
76       */
77      public void addResult(int opCode, int resultType);
78  
79      /**
80       * <P>Adds a constraint on the persistent field specified by
81       * <code>name</code>. The valid values for <code>operation
82       * </code> are defined in <b>ActionDesc</b>. The parameter
83       * <code>value</code> specifies the constraint value.
84       * <P>By default, multiple constraints are implicitly ANDed together.
85       * If the applications want to OR together the constraints,
86       * it can explicitly add <b>OP_OR</b> constraints. For example,
87       * to OR together two constraints, an application can do the following:
88       * <PRE>
89       * addConstraint("field1", ActionDesc.OP_EQ, "field1Value");
90       * addConstraint("field2", ActionDesc.OP_EQ, "field2Value");
91       * addConstraint(null, ActionDesc.OP_OR, null);
92       * </PRE>
93       * <P>The important thing to note about the above example is
94       * that the constraints are processed in postfix order, so
95       * the above example should be read as
96       * <PRE>
97       * (field1 == "field1Value") OR (field2 == "field2Value")
98       * </PRE>
99       */
100     public void addConstraint(String   name, int operation, Object   value);
101 
102     /**
103      * <P>Adds a constraint on the foreign field specified by
104      * <code>name</code>. This method is used to specify a relationship
105      * navigation on field <code>name</code> to the class represented by
106      * the retrieve descriptor <code>foreignConstraint</code>.
107      * If <code>name</code> is null, an unrelated constraint is added.
108      * A constraint is unrelated, if there is neither a foreign field
109      * nor a local field connecting to the retrieve descriptor
110      * <code>foreignConstraint</code>.
111      */
112     void addConstraint(String   name, RetrieveDesc foreignConstraint);
113 
114     /**
115      * <P>Adds a constraint on the field specified by <code>name</code>.
116      * This method is useful e.g. for comparisons of local fields with field of a related object:
117      *   emp.addConstraint("lastName", ActionDesc.OP_EQ, mgr, lastName");
118      * compares the employee's lastName field with the lastName field of the related manager.
119      */
120     void addConstraint(String   name, int operator, RetrieveDesc foreignConstraint, String   foreignFieldName);
121 
122     /**
123      * Sets a navigational id on the retrieve descriptor.
124      * This id will be used to discriminate different retrieve descriptors which
125      * use the same navigational field.
126      */
127     void setNavigationalId(Object   navigationalId);
128 
129     /** Sets the prefetchEnabled option.
130      *
131      * The prefetchEnabled option specifies whether prefetch of relationship
132      * fields should be enabled for this retrieve descriptor. The prefetch
133      * is enabled by default if such fields are part of DFG. A user needs
134      * to explicitely disable prefetch for any particular query if the related
135      * instances will not be used in this transaction.
136      *
137      * @param prefetchEnabled the setting of the prefetchEnabled option.
138      */
139     void setPrefetchEnabled(boolean prefetchEnabled);
140 }
141
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags