001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: *
017: * $Header:$
018: */
019: package org.apache.beehive.netui.core.urltemplates;
020:
021: import java.util.Collection;
022: import javax.servlet.ServletContext;
023: import javax.servlet.ServletRequest;
024:
025: import org.apache.beehive.netui.core.factory.Factory;
026:
027: /**
028: * Access point to URL templates (an optional config file to help format
029: * rewritten URLs) used by a {@link org.apache.beehive.netui.core.urls.TemplatedURLFormatter}
030: * via the {@link org.apache.beehive.netui.core.urls.URLRewriterService}.
031: */
032: public abstract class URLTemplatesFactory extends Factory {
033: private static final String URL_TEMPLATE_FACTORY_ATTR = "_netui:urlTemplatesFactory";
034:
035: // Constants for URL template types
036: public static final String DEFAULT_TEMPLATE = "default";
037: public static final String SECURE_DEFAULT_TEMPLATE = "secure-default";
038: public static final String ACTION_TEMPLATE = "action";
039: public static final String SECURE_ACTION_TEMPLATE = "secure-action";
040: public static final String RESOURCE_TEMPLATE = "resource";
041: public static final String SECURE_RESOURCE_TEMPLATE = "secure-resource";
042: public static final String RENDER_TEMPLATE = "render";
043: public static final String SECURE_RENDER_TEMPLATE = "secure-render";
044:
045: /** Default value for path from the web app to the URL templates. */
046: public static final String DEFAULT_URL_TEMPLATE_CONFIG_FILE_PATH = "/WEB-INF/beehive-url-template-config.xml";
047:
048: // Path to the URL templates config file.
049: protected String _configFilePath = DEFAULT_URL_TEMPLATE_CONFIG_FILE_PATH;
050:
051: // The known tokens (collection of String objects) in a valid template.
052: protected Collection _knownTokens = null;
053:
054: // The required tokens (collection of String objects) in a valid template.
055: protected Collection _requiredTokens = null;
056:
057: /**
058: * Gets the URLTemplatesFactory instance from a ServletContext attribute.
059: *
060: * @param servletContext the current ServletContext.
061: * @return the URLTemplatesFactory instance from the ServletContext.
062: */
063: public static URLTemplatesFactory getURLTemplatesFactory(
064: ServletContext servletContext) {
065: assert servletContext != null : "The ServletContext cannot be null.";
066:
067: if (servletContext == null) {
068: throw new IllegalArgumentException(
069: "The ServletContext cannot be null.");
070: }
071:
072: return (URLTemplatesFactory) servletContext
073: .getAttribute(URL_TEMPLATE_FACTORY_ATTR);
074: }
075:
076: /**
077: * Adds a given URLTemplatesFactory instance as an attribute on the ServletContext.
078: *
079: * @param servletContext the current ServletContext.
080: * @param templatesFactory the URLTemplatesFactory instance to add as an attribute of the context
081: */
082: public static void initServletContext(
083: ServletContext servletContext,
084: URLTemplatesFactory templatesFactory) {
085: assert servletContext != null : "The ServletContext cannot be null.";
086:
087: if (servletContext == null) {
088: throw new IllegalArgumentException(
089: "The ServletContext cannot be null.");
090: }
091:
092: servletContext.setAttribute(URL_TEMPLATE_FACTORY_ATTR,
093: templatesFactory);
094: }
095:
096: /**
097: * Gets the URLTemplatesFactory instance from a ServletRequest attribute.
098: *
099: * @param servletRequest the current ServletRequest.
100: * @return the URLTemplatesFactory instance from the ServletRequest.
101: */
102: public static URLTemplatesFactory getURLTemplatesFactory(
103: ServletRequest servletRequest) {
104: assert servletRequest != null : "The ServletRequest cannot be null.";
105:
106: if (servletRequest == null) {
107: throw new IllegalArgumentException(
108: "The ServletRequest cannot be null.");
109: }
110:
111: return (URLTemplatesFactory) servletRequest
112: .getAttribute(URL_TEMPLATE_FACTORY_ATTR);
113: }
114:
115: /**
116: * Adds a given URLTemplatesFactory instance as an attribute on the ServletRequest.
117: *
118: * @param servletRequest the current ServletRequest.
119: * @param templatesFactory the URLTemplatesFactory instance to add as an attribute of the request
120: */
121: public static void initServletRequest(
122: ServletRequest servletRequest,
123: URLTemplatesFactory templatesFactory) {
124: assert servletRequest != null : "The ServletRequest cannot be null.";
125:
126: if (servletRequest == null) {
127: throw new IllegalArgumentException(
128: "The ServletRequest cannot be null.");
129: }
130:
131: servletRequest.setAttribute(URL_TEMPLATE_FACTORY_ATTR,
132: templatesFactory);
133: }
134:
135: /**
136: * Allow clients to set their own URL template config file name/path.
137: *
138: * @param configFilePath An absolute path from the web app root to the URL template config file.
139: */
140: public void setConfigFilePath(String configFilePath) {
141: if (configFilePath == null) {
142: throw new IllegalArgumentException(
143: "Config file path cannot be null.");
144: }
145:
146: _configFilePath = configFilePath;
147: }
148:
149: /**
150: * Allow clients to define a set of known tokens for the
151: * template verification. Tokens are expected to be qualified
152: * in braces. E.g. {url:path}
153: * <p/>
154: * The template verification will ensure the known tokens in the
155: * URL template conforms to a valid format.
156: *
157: * @param knownTokens The set of known tokens for a valid template.
158: */
159: public void setKnownTokens(Collection knownTokens) {
160: _knownTokens = knownTokens;
161: }
162:
163: /**
164: * Allow clients to define a set of required tokens for the
165: * template verification. Tokens are expected to be qualified
166: * in braces. E.g. {url:path}
167: * <p>
168: * The template verification will ensure the URL template conforms to
169: * a valid format for known tokens and contains the required tokens.
170: * </p>
171: *
172: * @param requiredTokens The set of required tokens in a valid template.
173: */
174: public void setRequiredTokens(Collection requiredTokens) {
175: _requiredTokens = requiredTokens;
176: }
177:
178: /**
179: * Returns an array of the URL templates.
180: *
181: * @return the URL templates
182: */
183: public abstract URLTemplate[] getURLTemplates();
184:
185: /**
186: * Returns URL template given the name of the template.
187: *
188: * @param name name of the template
189: * @return template
190: */
191: public abstract URLTemplate getURLTemplate(String name);
192:
193: /**
194: * Returns URL template name of the given type (by key) from the
195: * desired reference group.
196: *
197: * @param refGroupName name of a group of templates from the config file.
198: * @param key type of the template
199: * @return template name
200: */
201: public abstract String getTemplateNameByRef(String refGroupName,
202: String key);
203:
204: /**
205: * Initialization method that parses the URL template config file to
206: * get the URL templates and template reference groups.
207: *
208: * @param servletContext the current ServletContext.
209: */
210: public abstract void load(ServletContext servletContext);
211: }
|