1 package org.apache.fulcrum.intake;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.beans.IntrospectionException;
23 import java.lang.reflect.Method;
24
25 import org.apache.fulcrum.intake.model.Group;
26
27 /**
28 * This service provides access to input processing objects based
29 * on an XML specification.
30 *
31 * <p>Localization of Intake's error messages can be accomplished
32 * using Turbine's <code>LocalizationTool</code> from a Velocity template
33 * as follows:
34 * <code>
35 * $l10n.get($intake.SomeGroup.SomeField.Message)
36 * </code>
37 * </p>
38 *
39 * @author <a href="mailto:jmcnally@collab.net">John McNally</a>
40 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
41 * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
42 * @version $Id$
43 */
44 public interface IntakeService
45 {
46 /** Avalon role - used to id the component within the manager */
47 String ROLE = IntakeService.class.getName();
48
49 /**
50 * The configuration property specifying the location of the xml specification.
51 */
52 String XML_PATHS = "xmlPaths";
53
54 /**
55 * The default location of the xml specification.
56 */
57 String XML_PATH_DEFAULT = "WEB-INF/conf/intake.xml";
58
59 /**
60 * The configuration property specifying the location where a serialized version of the
61 * xml specification can be written for faster restarts..
62 */
63 String SERIAL_XML = "serialDataPath";
64
65 /**
66 * The default location where a serialized version of
67 * the xml specification can be written for faster restarts..
68 */
69 String SERIAL_XML_DEFAULT = "WEB-INF/appData.ser";
70
71 /**
72 * The default pool capacity.
73 */
74 int DEFAULT_POOL_CAPACITY = 1024;
75
76 /**
77 * Gets an instance of a named group either from the pool
78 * or by calling the Factory Service if the pool is empty.
79 *
80 * @param groupName the name of the group.
81 * @return a Group instance.
82 * @throws IntakeException if recycling fails.
83 */
84 Group getGroup(String groupName)
85 throws IntakeException;
86
87 /**
88 * Puts a group back to the pool.
89 * @param instance the object instance to recycle.
90 *
91 * @throws IntakeException The passed group name does not exist.
92 */
93 void releaseGroup(Group instance)
94 throws IntakeException;
95
96 /**
97 * Gets the current size of the pool for a named group.
98 *
99 * @param groupName the name of the group.
100 * @return the size of the group pool
101 * @throws IntakeException The passed group name does not exist.
102 */
103 int getSize(String groupName)
104 throws IntakeException;
105
106 /**
107 * Names of all the defined groups.
108 *
109 * @return array of names.
110 */
111 String[] getGroupNames();
112
113 /**
114 * Gets the key (usually a short identifier) for a group.
115 *
116 * @param groupName the name of the group.
117 * @return the key.
118 */
119 String getGroupKey(String groupName);
120
121 /**
122 * Gets the group name given its key.
123 *
124 * @param groupKey the key.
125 * @return groupName the name of the group.
126 */
127 String getGroupName(String groupKey);
128
129 /**
130 * Gets the Method that can be used to set a property.
131 *
132 * @param className the name of the object.
133 * @param propName the name of the property.
134 * @return the setter.
135 * @throws ClassNotFoundException if the class specified could not be loaded
136 * @throws IntrospectionException if the property setter could not be called
137 */
138 Method getFieldSetter(String className, String propName)
139 throws ClassNotFoundException, IntrospectionException;
140
141 /**
142 * Gets the Method that can be used to get a property value.
143 *
144 * @param className the name of the object.
145 * @param propName the name of the property.
146 * @return the getter.
147 * @throws ClassNotFoundException if the class specified could not be loaded
148 * @throws IntrospectionException if the property getter could not be called
149 */
150 Method getFieldGetter(String className, String propName)
151 throws ClassNotFoundException, IntrospectionException;
152 }