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: package org.apache.jetspeed.profiler;
018:
019: import java.util.Iterator;
020:
021: import org.apache.jetspeed.profiler.ProfileLocatorProperty;
022: import org.apache.jetspeed.profiler.rules.RuleCriterion;
023:
024: /**
025: * <p>Profile Locators are used to locate profiled portal resources such as
026: * pages, documents, and fragments. A locator contains properties describing
027: * the actually resource to be located. Since the locator is based on properties
028: * that are usually related to a user or other subject's profile, it is referred
029: * to as a profile locator.</p>
030: *
031: * <p>Profiles can be created from a normalized <i>Profile Locator Path</i>
032: * The format of the path is name/value pairs of all property, separated by a <i>path separator</i>.
033: * An example locator path:</p>
034: *
035: * <pre>page:default.psml:artist:al-stewart:song:on-the-border</pre>
036: * <pre>path:/sports/football/nfl/chiefs:language:en</pre>
037: *
038: *
039: * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
040: * @version $Id: ProfileLocator.java 516448 2007-03-09 16:25:47Z ate $
041: */
042: public interface ProfileLocator {
043: public final static String PAGE_LOCATOR = "page";
044: public final static String SECURITY_LOCATOR = "security";
045:
046: public final static String PATH_SEPARATOR = ":";
047:
048: /**
049: * Initialize this page context.
050: *
051: * @param profiler The profiler initializing this locator.
052: * @param requestPath The request path used to create this locator.
053: */
054: void init(Profiler profiler, String requestPath);
055:
056: /**
057: * Get an iterator over the locator's properties.
058: * Elements are returned as @link ProfileLocatorProperty array.
059: *
060: * @return an iterator over the profile locator properties
061: */
062: Iterator iterator();
063:
064: /**
065: * Add a property based on a @link org.apache.jetspeed.profiler.rules.RuleCriterion
066: * and a value. Rule criteria are templates for locating profile properties.
067: * The value is combined with the rule to create a property.
068: *
069: * @param criterion The rule criterion on which this property is based.
070: * @param isControl The control classification for property.
071: * @param isNavigation The navigation classification for property.
072: * @param value The value to set on the property.
073: */
074: void add(RuleCriterion criterion, boolean isControl,
075: boolean isNavigation, String value);
076:
077: /**
078: * Add a property based on a Simple name and value.
079: *
080: * @param name The name of the property.
081: * @param isControl The control classification for property.
082: * @param isNavigation The control classification for property.
083: * @param value The value to set on the property.
084: */
085: void add(String name, boolean isControl, boolean isNavigation,
086: String value);
087:
088: /**
089: * Add a property based on a Simple name and value assumed
090: * to be control property.
091: *
092: * @param name The name of the property.
093: * @param value The value to set on the property.
094: */
095: void add(String name, String value);
096:
097: /**
098: * For a given property name, get a property of type @link ProfileLocatorProperty
099: *
100: * @param name The name of the property
101: * @return a property of type @link ProfileLocatorProperty
102: */
103: String getValue(String name);
104:
105: /**
106: * For a given property name, return control status of property.
107: *
108: * @param name The name of the property
109: * @return control classification flag
110: */
111: boolean isControl(String name);
112:
113: /**
114: * For a given property name, return navigation status of property.
115: *
116: * @param name The name of the property
117: * @return navigation classification flag
118: */
119: boolean isNavigation(String name);
120:
121: /**
122: * <p>Profiles can be created from a normalized <i>Profile Locator Path</i>
123: * The format of the path is name:value pairs of all property, separated by a <i>path separator</i>.
124: * Note: all locator property elements are assumed to be control properties.
125: * An example locator path:</p>
126: *
127: * <pre>:page:default.psml:artist:air:song:all-i-need</pre>
128: *
129: * @param path The normalized path as shown above from which the locator is created.
130: */
131: void createFromLocatorPath(String path);
132:
133: /**
134: * <p>Profiles can be converted to a normalized <i>Profile Locator Path</i>
135: * The format of the path is name/value pairs of all property, separated by a <i>path separator</i>.
136: * An example locator path:</p>
137: *
138: * <pre>:page:default.psml:artist:joni-mitchell:song:cary</pre>
139: *
140: * @return The normalized path as shown above.
141: */
142: String getLocatorPath();
143:
144: /**
145: * <p>Normalize profile properties obtained from profile locator iterators
146: * into a <i>Profile Locator Path</i>.</p>
147: *
148: * @param properties The array of profile properties.
149: * @return The normalized path for properties.
150: */
151: String getLocatorPath(ProfileLocatorProperty[] properties);
152:
153: /**
154: * Returns a normalized path. @see #getLocatorPath()
155: *
156: * @return The normalized path representation of this locator.
157: */
158: String toString();
159:
160: /**
161: * <p>Locators are intended to be sufficient to locate managed pages, so the request
162: * path must be generally available in the event it is not otherwise captured in a
163: * rule criterion.</p>
164: *
165: * @return The request path.
166: */
167: String getRequestPath();
168: }
|