1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.jetspeed.profiler;
18
19 import java.util.Iterator;
20
21 import org.apache.jetspeed.profiler.ProfileLocatorProperty;
22 import org.apache.jetspeed.profiler.rules.RuleCriterion;
23
24 /***
25 * <p>Profile Locators are used to locate profiled portal resources such as
26 * pages, documents, and fragments. A locator contains properties describing
27 * the actually resource to be located. Since the locator is based on properties
28 * that are usually related to a user or other subject's profile, it is referred
29 * to as a profile locator.</p>
30 *
31 * <p>Profiles can be created from a normalized <i>Profile Locator Path</i>
32 * The format of the path is name/value pairs of all property, separated by a <i>path separator</i>.
33 * An example locator path:</p>
34 *
35 * <pre>page:default.psml:artist:al-stewart:song:on-the-border</pre>
36 * <pre>path:/sports/football/nfl/chiefs:language:en</pre>
37 *
38 *
39 * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
40 * @version $Id: ProfileLocator.java 516448 2007-03-09 16:25:47Z ate $
41 */
42 public interface ProfileLocator
43 {
44 public final static String PAGE_LOCATOR = "page";
45 public final static String SECURITY_LOCATOR = "security";
46
47 public final static String PATH_SEPARATOR = ":";
48
49 /***
50 * Initialize this page context.
51 *
52 * @param profiler The profiler initializing this locator.
53 * @param requestPath The request path used to create this locator.
54 */
55 void init(Profiler profiler, String requestPath);
56
57 /***
58 * Get an iterator over the locator's properties.
59 * Elements are returned as @link ProfileLocatorProperty array.
60 *
61 * @return an iterator over the profile locator properties
62 */
63 Iterator iterator();
64
65 /***
66 * Add a property based on a @link org.apache.jetspeed.profiler.rules.RuleCriterion
67 * and a value. Rule criteria are templates for locating profile properties.
68 * The value is combined with the rule to create a property.
69 *
70 * @param criterion The rule criterion on which this property is based.
71 * @param isControl The control classification for property.
72 * @param isNavigation The navigation classification for property.
73 * @param value The value to set on the property.
74 */
75 void add(RuleCriterion criterion, boolean isControl, boolean isNavigation, String value);
76
77 /***
78 * Add a property based on a Simple name and value.
79 *
80 * @param name The name of the property.
81 * @param isControl The control classification for property.
82 * @param isNavigation The control classification for property.
83 * @param value The value to set on the property.
84 */
85 void add(String name, boolean isControl, boolean isNavigation, String value);
86
87 /***
88 * Add a property based on a Simple name and value assumed
89 * to be control property.
90 *
91 * @param name The name of the property.
92 * @param value The value to set on the property.
93 */
94 void add(String name, String value);
95
96 /***
97 * For a given property name, get a property of type @link ProfileLocatorProperty
98 *
99 * @param name The name of the property
100 * @return a property of type @link ProfileLocatorProperty
101 */
102 String getValue(String name);
103
104 /***
105 * For a given property name, return control status of property.
106 *
107 * @param name The name of the property
108 * @return control classification flag
109 */
110 boolean isControl(String name);
111
112 /***
113 * For a given property name, return navigation status of property.
114 *
115 * @param name The name of the property
116 * @return navigation classification flag
117 */
118 boolean isNavigation(String name);
119
120 /***
121 * <p>Profiles can be created from a normalized <i>Profile Locator Path</i>
122 * The format of the path is name:value pairs of all property, separated by a <i>path separator</i>.
123 * Note: all locator property elements are assumed to be control properties.
124 * An example locator path:</p>
125 *
126 * <pre>:page:default.psml:artist:air:song:all-i-need</pre>
127 *
128 * @param path The normalized path as shown above from which the locator is created.
129 */
130 void createFromLocatorPath(String path);
131
132 /***
133 * <p>Profiles can be converted to a normalized <i>Profile Locator Path</i>
134 * The format of the path is name/value pairs of all property, separated by a <i>path separator</i>.
135 * An example locator path:</p>
136 *
137 * <pre>:page:default.psml:artist:joni-mitchell:song:cary</pre>
138 *
139 * @return The normalized path as shown above.
140 */
141 String getLocatorPath();
142
143 /***
144 * <p>Normalize profile properties obtained from profile locator iterators
145 * into a <i>Profile Locator Path</i>.</p>
146 *
147 * @param properties The array of profile properties.
148 * @return The normalized path for properties.
149 */
150 String getLocatorPath(ProfileLocatorProperty [] properties);
151
152 /***
153 * Returns a normalized path. @see #getLocatorPath()
154 *
155 * @return The normalized path representation of this locator.
156 */
157 String toString();
158
159 /***
160 * <p>Locators are intended to be sufficient to locate managed pages, so the request
161 * path must be generally available in the event it is not otherwise captured in a
162 * rule criterion.</p>
163 *
164 * @return The request path.
165 */
166 String getRequestPath();
167 }