1 /**
2 * Copyright 2005-2012 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.cache;
17
18 import org.apache.commons.lang.StringUtils;
19 import org.kuali.rice.core.api.CoreConstants;
20 import org.kuali.rice.core.api.mo.AbstractDataTransferObject;
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 java.util.Collection;
30
31 @XmlRootElement(name = CacheTarget.Constants.ROOT_ELEMENT_NAME)
32 @XmlAccessorType(XmlAccessType.NONE)
33 @XmlType(name = CacheTarget.Constants.TYPE_NAME, propOrder = {
34 CacheTarget.Elements.CACHE,
35 CacheTarget.Elements.KEY,
36 CoreConstants.CommonElements.FUTURE_ELEMENTS
37 })
38 /**
39 * A class that represents a target of a cache operation. If the cache key is not specified then the entire cache is
40 * the target.
41 *
42 * @author Kuali Rice Team (rice.collab@kuali.org)
43 * @since 2.0
44 */
45 public final class CacheTarget extends AbstractDataTransferObject {
46
47 private static final long serialVersionUID = -7143135771254777648L;
48
49 @XmlElement(name = Elements.CACHE, required = true)
50 private final String cache;
51
52 @XmlElement(name = Elements.KEY, required = false)
53 private final String key;
54
55 @SuppressWarnings("unused")
56 @XmlAnyElement
57 private final Collection<Element> _futureElements = null;
58
59 /**
60 * This constructor should never be called except during JAXB unmarshalling.
61 */
62 @SuppressWarnings("unused")
63 private CacheTarget() {
64 this.cache = null;
65 this.key = null;
66 }
67
68 private CacheTarget(String cache, String key) {
69 if (StringUtils.isBlank(cache)) {
70 throw new IllegalArgumentException("cache is blank or null");
71 }
72 this.cache = cache;
73 this.key = key;
74 }
75
76 /**
77 * Creates an instance targeting an entire cache.
78 *
79 * @param cache the name of the cache. cannot be a null or blank string
80 *
81 * @return an instance of the cache target specified
82 *
83 * @throws IllegalArgumentException if cache is null or blank
84 */
85 public static CacheTarget entireCache(String cache) {
86 return new CacheTarget(cache, null);
87 }
88
89 /**
90 * Creates an instance targeting a single item in a cache based on the given key.
91 *
92 * @param cache The name of the cache. cannot be a null or blank string.
93 * @param key The key of the item in the cache. cannot be a null of blank string.
94 *
95 * @return an instance of the cache target specified
96 *
97 * @throws IllegalArgumentException if the cache or key is null or blank
98 */
99 public static CacheTarget singleEntry(String cache, String key) {
100 if (StringUtils.isBlank(key)) {
101 throw new IllegalArgumentException("a blank or null key does not target a single entry");
102 }
103 return new CacheTarget(cache, key);
104 }
105
106 /**
107 * Checks if this instance contains a key.
108 *
109 * @return true if a key exists, false otherwise
110 */
111 public boolean containsKey() {
112 return key != null;
113 }
114
115 /**
116 * The name of the cache to target. This value should never be null or blank.
117 *
118 * @return the name of the cache
119 */
120 public String getCache() {
121 return cache;
122 }
123
124 /**
125 * The key of the item in the cache to target. The key is optional on the cache target, if this target has no key
126 * then this method will return null.
127 *
128 * @return the key of this cache target, or null if a specific key is not being targeted
129 */
130 public String getKey() {
131 return key;
132 }
133
134 /**
135 * Defines some internal constants used on this class.
136 */
137 static class Constants {
138 final static String ROOT_ELEMENT_NAME = "cacheTarget";
139 final static String TYPE_NAME = "CacheTargetType";
140 }
141
142 /**
143 * A private class which exposes constants which define the XML element names to use
144 * when this object is marshalled to XML.
145 */
146 static class Elements {
147 final static String CACHE = "cache";
148 final static String KEY = "key";
149 }
150
151 }