View Javadoc

1   /**
2    * Copyright 2005-2013 The Kuali Foundation
3    *
4    * Licensed under the Educational Community License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.opensource.org/licenses/ecl2.php
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.kuali.rice.core.api.criteria;
17  
18  import org.kuali.rice.core.api.CoreConstants;
19  import org.kuali.rice.core.api.mo.AbstractDataTransferObject;
20  import org.kuali.rice.core.api.mo.ModelBuilder;
21  import org.kuali.rice.core.api.util.collect.CollectionUtils;
22  import org.w3c.dom.Element;
23  
24  import javax.xml.bind.annotation.XmlAccessType;
25  import javax.xml.bind.annotation.XmlAccessorType;
26  import javax.xml.bind.annotation.XmlAnyElement;
27  import javax.xml.bind.annotation.XmlElement;
28  import javax.xml.bind.annotation.XmlElementWrapper;
29  import javax.xml.bind.annotation.XmlElements;
30  import javax.xml.bind.annotation.XmlRootElement;
31  import javax.xml.bind.annotation.XmlType;
32  import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
33  import java.io.Serializable;
34  import java.util.ArrayList;
35  import java.util.Arrays;
36  import java.util.Collection;
37  import java.util.List;
38  
39  /**
40   * Defines a criteria-based query.  Consists of a {@link org.kuali.rice.core.api.criteria.Predicate} definition
41   * as well as a set of additional properties which control paging and other
42   * aspects of the results which should be returned from the query.
43   *
44   * <p>In order to construct a new {@link org.kuali.rice.core.api.criteria.OrderByField}, the {@link Builder}
45   * should be used.  Use the {@link org.kuali.rice.core.api.criteria.PredicateFactory} to construct
46   * the predicate for use by the query.
47   *
48   * <p>This class specifies nothing regarding how the query will be executed.
49   * It is expected that an instance will be constructed and then passed to code
50   * which understands how to execute the desired query.
51   *
52   * <p>This class is mapped for use by JAXB and can therefore be used by clients
53   * as part of remotable service definitions.
54   *
55   * @see org.kuali.rice.core.api.criteria.Predicate
56   * @see org.kuali.rice.core.api.criteria.PredicateFactory
57   *
58   * @author Kuali Rice Team (rice.collab@kuali.org)
59   *
60   */
61  @XmlRootElement(name = OrderByField.Constants.ROOT_ELEMENT_NAME)
62  @XmlAccessorType(XmlAccessType.NONE)
63  @XmlType(name = OrderByField.Constants.TYPE_NAME, propOrder = {
64  		OrderByField.Elements.FIELD_NAME,
65          OrderByField.Elements.ORDER_DIRECTION,
66  		CoreConstants.CommonElements.FUTURE_ELEMENTS })
67  public final class OrderByField extends AbstractDataTransferObject {
68  
69  	private static final long serialVersionUID = 2210627777648920185L;
70  
71  	@XmlElement(name = Elements.FIELD_NAME, required = true)
72  	private final String fieldName;
73  
74      @XmlJavaTypeAdapter(OrderDirection.Adapter.class)
75      @XmlElement(name = Elements.ORDER_DIRECTION, required = true)
76      private final String orderDirection;
77  
78  	@SuppressWarnings("unused")
79  	@XmlAnyElement
80  	private final Collection<Element> _futureElements = null;
81  
82  	private OrderByField() {
83          this.fieldName = null;
84          this.orderDirection = null;
85  	}
86  
87  	private OrderByField(Builder builder) {
88  		this.fieldName = builder.getFieldName();
89          this.orderDirection = builder.getOrderDirection() == null ? null : builder.getOrderDirection().getDirection();
90  	}
91  
92  
93      /**
94       * Returns the a name of the field to order results on
95       *
96       * @return field names that will affect the order of the returned rows
97       */
98      public String getFieldName() {
99          return this.fieldName;
100     }
101 
102     /**
103      * Indicates what direction row ordering is used (ascending or descending)
104      *
105      * @return the flag specifying whether or not ascending or descending order is used
106      */
107     public OrderDirection getOrderDirection() {
108         return this.orderDirection == null ? null : OrderDirection.valueOf(this.orderDirection);
109     }
110 
111 
112 	public static final class Builder implements ModelBuilder, Serializable {
113 
114         private String fieldName;
115         private OrderDirection orderDirection;
116 
117 		private Builder() {
118             setOrderDirection(OrderDirection.ASCENDING);
119 		}
120 
121         private Builder(String fieldName, OrderDirection orderDirection) {
122             setOrderDirection(orderDirection);
123             setFieldName(fieldName);
124         }
125 
126 		public static Builder create() {
127             return new Builder();
128 		}
129 
130         public static Builder create(String fieldName, OrderDirection orderDirection) {
131             return new Builder(fieldName, orderDirection);
132         }
133 
134         public OrderDirection getOrderDirection() {
135             return this.orderDirection;
136         }
137 
138         public void setOrderDirection(OrderDirection orderDirection) {
139             if (orderDirection == null) {
140                 throw new IllegalArgumentException("orderDirection was null");
141             }
142             this.orderDirection = orderDirection;
143         }
144 
145         public String getFieldName() {
146             return this.fieldName;
147         }
148 
149         public void setFieldName(String fieldName) {
150             if (fieldName == null) {
151                 throw new IllegalArgumentException("fieldName was null");
152             }
153             this.fieldName = fieldName;
154         }
155 
156 
157 
158         @Override
159         public OrderByField build() {
160             return new OrderByField(this);
161         }
162 
163     }
164 
165 	/**
166 	 * Defines some internal constants used on this class.
167 	 */
168 	static class Constants {
169 		final static String ROOT_ELEMENT_NAME = "orderByField";
170 		final static String TYPE_NAME = "OrderByFieldType";
171 	}
172 
173 	/**
174 	 * A private class which exposes constants which define the XML element
175 	 * names to use when this object is marshaled to XML.
176 	 */
177 	static class Elements {
178         final static String FIELD_NAME = "fieldName";
179         final static String ORDER_DIRECTION = "orderDirection";
180 	}
181 
182 }