KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > oracle > toplink > essentials > queryframework > FetchGroup


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
5  * in compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * glassfish/bootstrap/legal/CDDLv1.0.txt or
9  * https://glassfish.dev.java.net/public/CDDLv1.0.html.
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 in each file and include the License file at
15  * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
16  * add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your
18  * own identifying information: Portions Copyright [yyyy]
19  * [name of copyright owner]
20  */
21 // Copyright (c) 1998, 2005, Oracle. All rights reserved.
22 package oracle.toplink.essentials.queryframework;
23
24 import java.util.*;
25 import oracle.toplink.essentials.expressions.Expression;
26
27 /**
28  * <p><b>Purpose</b>: A fetch group is a performance enhancement that allows a group of
29  * attributes of an object to be loaded on demand, which means that the data for an attribute
30  * might not loaded from the underlying data source until an explicit access call for the
31  * attribute first occurs. It avoids the wasteful practice of loading up all data of the object?s
32  * attributes, in which the user is interested in only partial of them.
33  *
34  * A great deal of caution and careful system use case analysis should be use when using the fetch
35  * group feature, as the extra round-trip would well offset the gain from the deferred loading in
36  * many cases.
37  *
38  * TopLink fetch group support is twofold: the pre-defined fetch groups at the descriptor level; and
39  * dynamic (use case) fetch groups at the query level.
40  *
41  * TopLink fetch group support is only on CMP project.
42  *
43  * Every query can has at most one fetch group. There is an optional pre-defined default fetch group
44  * at the descriptor level. If set, and the query has no fetch group being set, the default fetch group
45  * would be used, unless query.setShouldUseDefaultFetchGroup(false) is also called. In the latter case,
46  * the full object will be fetched after the query execution.
47  *
48  * @see oracle.toplink.essentials.queryframework.FetchGroup
49  * @see oracle.toplink.essentials.queryframework.FetchGroupTracker
50  *
51  * @author King Wang
52  * @since TopLink 10.1.3.
53  */
54 public class FetchGroup implements java.io.Serializable JavaDoc {
55     //fetch group name, default is empty if not set
56 private String JavaDoc name = "";
57
58     //all attributes in the group
59 private Set attributes = new TreeSet();
60
61     //attibute expression list used for the query preparation
62 private List fetchGroupAttributeExpressions;
63
64     /**
65      * Constructor.
66      */
67     public FetchGroup() {
68         this("");
69     }
70
71     /**
72      * Constructor with a group name.
73      */
74     public FetchGroup(String JavaDoc name) {
75         this.name = name;
76         this.fetchGroupAttributeExpressions = new ArrayList();
77     }
78
79     /**
80      * Return all attributes defined in the group
81      */
82     public Set getAttributes() {
83         return attributes;
84     }
85
86     /**
87      * Add an attribute to the group
88      */
89     public void addAttribute(String JavaDoc attrName) {
90         attributes.add(attrName);
91     }
92
93     /**
94      * Add a set of attributes to the group
95      */
96     public void addAttributes(Set newAttributes) {
97         attributes.addAll(newAttributes);
98     }
99
100     /**
101     * Remove an attribute from the group
102     */
103     public void removeAttribute(String JavaDoc attrName) {
104         attributes.remove(attrName);
105     }
106
107     /**
108      * Return the group name
109      */
110     public String JavaDoc getName() {
111         return name;
112     }
113
114     /**
115      * Set the group name
116      */
117     public void setName(String JavaDoc name) {
118         this.name = name;
119     }
120
121     /**
122      * INTERNAL:
123      * Return true if this fetch group is a super-set of the passed in fetch group
124      */
125     public boolean isSupersetOf(FetchGroup anotherGroup) {
126         return (anotherGroup != null) && getAttributes().containsAll(anotherGroup.getAttributes());
127     }
128
129     /**
130      * INTERNAL:
131      * Return the attibute expression list.
132      */
133     public List getFetchGroupAttributeExpressions() {
134         return fetchGroupAttributeExpressions;
135     }
136
137     /**
138      * INTERNAL:
139      * Set the attibute expression list.
140      */
141     public void setFetchGroupAttributeExpressions(List fetchGroupAttributeExpressions) {
142         this.fetchGroupAttributeExpressions = fetchGroupAttributeExpressions;
143     }
144
145     /**
146      * INTERNAL:
147      * Return if fetch group attributes.
148      */
149     public boolean hasFetchGroupAttributeExpressions() {
150         return !fetchGroupAttributeExpressions.isEmpty();
151     }
152
153     /**
154     * INTERNAL:
155     * Specify that only a subset of the class' attributes be fetched in this query.
156     * <p>This allows for the query to be optimized through selecting less data.
157     * <p>Partial objects will be returned from the query, where the unspecified attributes will be left in their default value.
158     * The primary key, and optimistic locking version (version or timestamp) if defined, will always be fetched.
159     * The partial object is cached and can be modified.
160     * An access through getter to an un-fetched attribute will trigger another SELECT to load the whole object.
161     * <p>Note: Modifying un-fetched attribute is not supported and exception would thrown.
162     */
163     public void addFetchGroupAttribute(Expression attributeExpression) {
164         getFetchGroupAttributeExpressions().add(attributeExpression);
165     }
166 }
167
Popular Tags