KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > jdo > spi > persistence > support > sqlstore > 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 JavaDoc 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 JavaDoc name, int operation, Object JavaDoc 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 JavaDoc 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 JavaDoc name, int operator, RetrieveDesc foreignConstraint, String JavaDoc 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 JavaDoc 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
Popular Tags