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.security.Principal;
020: import java.util.Collection;
021: import java.util.Map;
022:
023: import org.apache.jetspeed.profiler.rules.PrincipalRule;
024: import org.apache.jetspeed.profiler.rules.ProfilingRule;
025: import org.apache.jetspeed.profiler.rules.RuleCriterion;
026: import org.apache.jetspeed.request.RequestContext;
027:
028: /**
029: * ProfilerService
030: * Jetspeed-2 Profiler service.
031: * Locates portal resources given a set of request parameters, properties, and attributes
032: * The Profiler is invoked during the request processing pipeline.
033: * It requires that the request context is already populated with the portal request and response,
034: * and capability and user information. The request context parameters, properties and attributes
035: * make up the profile criterion which the profiler uses to locate portal resources:
036: * 1. page
037: * 2. navigations
038: * 3. document lists
039: *
040: * In all cases, a fallback algorithm should be applied to fallback
041: * to default portal resources.
042: *
043: * @author <a href="mailto:taylor@apache.org">David Sean Taylor</a>
044: * @version $Id: Profiler.java 516881 2007-03-11 10:34:21Z ate $
045: */
046: public interface Profiler {
047:
048: /**
049: * Get the Profile object using the request parameters.
050: *
051: * @param context The request context
052: * @param locatorName The name of the profile locator to find i.e. "page", "docset", ...
053: * @return a new Profile Locator object or null if failed to find a appropriate locator.
054: */
055: ProfileLocator getProfile(RequestContext context, String locatorName)
056: throws ProfilerException;
057:
058: /**
059: *
060: * <p>
061: * getDefaultProfile
062: * </p>
063: * Intstead of using the princpal found within the request, the DEFAULT_RULE_PRINCIPAL is used.
064: *
065: * @param context The request context
066: * @param locatorName The name of the profile locator to find i.e. "page", "docset", ...
067: * @return a new Profile Locator object or null if failed to find a appropriate locator.
068: */
069: ProfileLocator getDefaultProfile(RequestContext context,
070: String locatorName) throws ProfilerException;
071:
072: /**
073: * Get the Profile object using the request parameters and the rule.
074: *
075: * @param context The request context
076: * @return a new Profile Locator object or null if failed to find a appropriate locator.
077: */
078: ProfileLocator getProfile(RequestContext context, ProfilingRule rule)
079: throws ProfilerException;
080:
081: /**
082: * Creates a new ProfileLocator object that can be managed by
083: * the current Profiler implementation
084: *
085: * @param context The request context
086: * @return A new ProfileLocator object
087: */
088: ProfileLocator createLocator(RequestContext context);
089:
090: /**
091: * For a given principal, lookup the associated profiling rule to that principal name.
092: *
093: * @param principal Lookup the profiling rule based on this principal.
094: * @param locatorName the unique name of a locator for this principal/rule/locator
095: * @return The rule found or null if not found
096: */
097: ProfilingRule getRuleForPrincipal(Principal principal,
098: String locatorName);
099:
100: /**
101: * For a given principal, associate a profiling rule to that principal name.
102: * TODO: this API should be secured and require admin role
103: *
104: * @param principal
105: * Lookup the profiling rule based on this principal.
106: * @param locatorName
107: * the unique name of a locator for this principal/rule/locator
108: * @param The
109: * rule used to find profiles for this user
110: */
111: void setRuleForPrincipal(Principal principal, ProfilingRule rule,
112: String locatorName);
113:
114: /**
115: * Lookup the portal's default profiling rule.
116: *
117: * @return The portal's default profiling rule.
118: */
119: ProfilingRule getDefaultRule();
120:
121: /**
122: * @return
123: */
124: Collection getRules();
125:
126: /**
127: * Given a rule id, get the rule
128: *
129: * @param id
130: * @return the rule
131: */
132: ProfilingRule getRule(String id);
133:
134: /**
135: * For a given principal, find all supported locators and return a string
136: * array of locator names.
137: *
138: * @param principal
139: * The given principal.
140: * @return array of String locator names
141: */
142: String[] getLocatorNamesForPrincipal(Principal principal);
143:
144: /**
145: * For a given principal, find all supported locators and return a
146: * collection of principal rules.
147: *
148: * @param principal
149: * The given principal.
150: * @return collection of PrincipalRules
151: */
152: Collection getRulesForPrincipal(Principal principal);
153:
154: /**
155: * Gets all supported locators for a principal.
156: *
157: * @param context
158: * @param principal
159: * @return
160: * @throws ProfilerException
161: */
162: Map getProfileLocators(RequestContext context, Principal principal)
163: throws ProfilerException;
164:
165: /**
166: *
167: * <p>
168: * getDefaultProfileLocators
169: * </p>
170: * Gets all the supported locators for the DEFAULT_RULE_PRINCIPAL
171: *
172: * @param context
173: * @return
174: * @throws ProfilerException
175: */
176: Map getDefaultProfileLocators(RequestContext context)
177: throws ProfilerException;
178:
179: /*
180: * Persist a profiling rule to the persistent store.
181: *
182: */
183: void storeProfilingRule(ProfilingRule rule)
184: throws ProfilerException;
185:
186: /*
187: * Deletes a profiling rule from the persistent store.
188: *
189: */
190: void deleteProfilingRule(ProfilingRule rule)
191: throws ProfilerException;
192:
193: /*
194: * Persist a principal rule to the persistent store.
195: *
196: */
197: void storePrincipalRule(PrincipalRule rule)
198: throws ProfilerException;
199:
200: /*
201: * Deletes a principal rule from the persistent store.
202: *
203: */
204: void deletePrincipalRule(PrincipalRule rule)
205: throws ProfilerException;
206:
207: /**
208: * Factory for Profiling Rule. The boolean argument specifies whether to
209: * obtain a new instance of a standard profiling rule or of a fallback rule.
210: *
211: * @param standard
212: * true if standard rule is requested, false if fallback
213: * @return New instance of a (standard or fallback) Profiling Rule
214: * @throws ClassNotFoundException
215: * if the beanfactory couldn't instantiate the bean
216: */
217: public ProfilingRule createProfilingRule(boolean standard)
218: throws ClassNotFoundException;
219:
220: /**
221: * Factory for PrincipalRule, the container to connect profiling rule and
222: * (user) prinicpal
223: * <p>
224: * Replaces the previous Class.forName and .instantiate logic with the
225: * Spring based factory.
226: *
227: * @return New instance of a principal rule
228: * @throws ClassNotFoundException
229: * if the beanfactory couldn't instantiate the bean
230: */
231: public PrincipalRule createPrincipalRule()
232: throws ClassNotFoundException;
233:
234: /**
235: * Factory for Rule Criterion
236: * <p>
237: *
238: * @return New instance of a rule criterion
239: * @throws ClassNotFoundException
240: * if the beanfactory couldn't instantiate the bean
241: */
242: public RuleCriterion createRuleCriterion()
243: throws ClassNotFoundException;
244:
245: /**
246: * Resets the default rule for this portal
247: * @param defaultRule
248: * The default rule to set.
249: */
250: public void setDefaultRule(String defaultRule);
251:
252: }
|