View Javadoc
1   /**
2    * Copyright 2005-2014 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.w3c.dom.Element;
22  
23  import javax.xml.bind.annotation.XmlAccessType;
24  import javax.xml.bind.annotation.XmlAccessorType;
25  import javax.xml.bind.annotation.XmlAnyElement;
26  import javax.xml.bind.annotation.XmlElement;
27  import javax.xml.bind.annotation.XmlRootElement;
28  import javax.xml.bind.annotation.XmlType;
29  import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
30  import java.io.Serializable;
31  import java.util.Collection;
32  
33  /**
34   * Defines a criteria-based query.  Consists of a {@link org.kuali.rice.core.api.criteria.Predicate} definition
35   * as well as a set of additional properties which control paging and other
36   * aspects of the results which should be returned from the query.
37   *
38   * <p>In order to construct a new {@link org.kuali.rice.core.api.criteria.OrderByField}, the {@link Builder}
39   * should be used.  Use the {@link org.kuali.rice.core.api.criteria.PredicateFactory} to construct
40   * the predicate for use by the query.
41   *
42   * <p>This class specifies nothing regarding how the query will be executed.
43   * It is expected that an instance will be constructed and then passed to code
44   * which understands how to execute the desired query.
45   *
46   * <p>This class is mapped for use by JAXB and can therefore be used by clients
47   * as part of remotable service definitions.
48   *
49   * @see org.kuali.rice.core.api.criteria.Predicate
50   * @see org.kuali.rice.core.api.criteria.PredicateFactory
51   *
52   * @author Kuali Rice Team (rice.collab@kuali.org)
53   *
54   */
55  @XmlRootElement(name = OrderByField.Constants.ROOT_ELEMENT_NAME)
56  @XmlAccessorType(XmlAccessType.NONE)
57  @XmlType(name = OrderByField.Constants.TYPE_NAME, propOrder = {
58  		OrderByField.Elements.FIELD_NAME,
59          OrderByField.Elements.ORDER_DIRECTION,
60  		CoreConstants.CommonElements.FUTURE_ELEMENTS })
61  public final class OrderByField extends AbstractDataTransferObject {
62  
63  	private static final long serialVersionUID = 2210627777648920185L;
64  
65  	@XmlElement(name = Elements.FIELD_NAME, required = true)
66  	private final String fieldName;
67  
68      @XmlJavaTypeAdapter(OrderDirection.Adapter.class)
69      @XmlElement(name = Elements.ORDER_DIRECTION, required = true)
70      private final String orderDirection;
71  
72  	@SuppressWarnings("unused")
73  	@XmlAnyElement
74  	private final Collection<Element> _futureElements = null;
75  
76  	private OrderByField() {
77          this.fieldName = null;
78          this.orderDirection = null;
79  	}
80  
81  	private OrderByField(Builder builder) {
82  		this.fieldName = builder.getFieldName();
83          this.orderDirection = builder.getOrderDirection() == null ? null : builder.getOrderDirection().getDirection();
84  	}
85  
86  
87      /**
88       * Returns the a name of the field to order results on
89       *
90       * @return field names that will affect the order of the returned rows
91       */
92      public String getFieldName() {
93          return this.fieldName;
94      }
95  
96      /**
97       * Indicates what direction row ordering is used (ascending or descending)
98       *
99       * @return the flag specifying whether or not ascending or descending order is used
100      */
101     public OrderDirection getOrderDirection() {
102         return this.orderDirection == null ? null : OrderDirection.valueOf(this.orderDirection);
103     }
104 
105 
106 	public static final class Builder implements ModelBuilder, Serializable {
107 
108         private String fieldName;
109         private OrderDirection orderDirection;
110 
111 		private Builder() {
112             setOrderDirection(OrderDirection.ASCENDING);
113 		}
114 
115         private Builder(String fieldName, OrderDirection orderDirection) {
116             setOrderDirection(orderDirection);
117             setFieldName(fieldName);
118         }
119 
120 		public static Builder create() {
121             return new Builder();
122 		}
123 
124         public static Builder create(String fieldName, OrderDirection orderDirection) {
125             return new Builder(fieldName, orderDirection);
126         }
127 
128         public OrderDirection getOrderDirection() {
129             return this.orderDirection;
130         }
131 
132         public void setOrderDirection(OrderDirection orderDirection) {
133             if (orderDirection == null) {
134                 throw new IllegalArgumentException("orderDirection was null");
135             }
136             this.orderDirection = orderDirection;
137         }
138 
139         public String getFieldName() {
140             return this.fieldName;
141         }
142 
143         public void setFieldName(String fieldName) {
144             if (fieldName == null) {
145                 throw new IllegalArgumentException("fieldName was null");
146             }
147             this.fieldName = fieldName;
148         }
149 
150 
151 
152         @Override
153         public OrderByField build() {
154             return new OrderByField(this);
155         }
156 
157     }
158 
159 	/**
160 	 * Defines some internal constants used on this class.
161 	 */
162 	static class Constants {
163 		final static String ROOT_ELEMENT_NAME = "orderByField";
164 		final static String TYPE_NAME = "OrderByFieldType";
165 	}
166 
167 	/**
168 	 * A private class which exposes constants which define the XML element
169 	 * names to use when this object is marshaled to XML.
170 	 */
171 	static class Elements {
172         final static String FIELD_NAME = "fieldName";
173         final static String ORDER_DIRECTION = "orderDirection";
174 	}
175 
176 }