001: /*****************************************************************************
002: * Java Plug-in Framework (JPF)
003: * Copyright (C) 2004-2007 Dmitry Olshansky
004: *
005: * This library is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU Lesser General Public
007: * License as published by the Free Software Foundation; either
008: * version 2.1 of the License, or (at your option) any later version.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General Public
016: * License along with this library; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: *****************************************************************************/package org.java.plugin.registry;
019:
020: import java.net.URL;
021: import java.util.Collection;
022: import java.util.Date;
023:
024: import org.java.plugin.PathResolver;
025: import org.java.plugin.registry.ExtensionPoint.ParameterDefinition;
026:
027: /**
028: * This interface abstracts an extension - particular functionality,
029: * the plug-in contribute to the system.
030: * <p>
031: * Extension UID is a combination of declaring plug-in ID and extension ID that
032: * is unique within whole set of registered plug-ins.
033: * </p>
034: *
035: * @version $Id$
036: */
037: public interface Extension extends UniqueIdentity,
038: PluginElement<Extension> {
039: /**
040: * Returns collection of all top level parameters defined in this extension.
041: * @return collection of {@link Extension.Parameter} objects
042: */
043: Collection<Parameter> getParameters();
044:
045: /**
046: * Returns top level parameter with given ID or <code>null</code> if no top
047: * level parameters exist. If more than one top level parameters with given
048: * ID found, the method should throw an {@link IllegalArgumentException}.
049: * @param id ID of parameter to look for
050: * @return top level parameter with given ID
051: */
052: Parameter getParameter(String id);
053:
054: /**
055: * @param id ID of parameter to look for
056: * @return collection of all top level parameters with given ID
057: */
058: Collection<Parameter> getParameters(String id);
059:
060: /**
061: * @return ID of plug-in, extended point belongs to
062: */
063: String getExtendedPluginId();
064:
065: /**
066: * @return ID of extended point
067: */
068: String getExtendedPointId();
069:
070: /**
071: * @return <code>true</code> if extension is considered to be valid
072: */
073: boolean isValid();
074:
075: /**
076: * This interface abstracts extension parameter according to extension
077: * declaration in manifest.
078: * @version $Id$
079: */
080: interface Parameter extends PluginElement<Parameter> {
081: /**
082: * @return parameter value as it is specified in manifest, if no value
083: * provided there, this method should return empty string
084: */
085: String rawValue();
086:
087: /**
088: * Returns collection of all sub-parameters defined in this parameter.
089: * @return collection of {@link Extension.Parameter} objects
090: */
091: Collection<Parameter> getSubParameters();
092:
093: /**
094: * Returns sub-parameter with given ID or <code>null</code> if no
095: * sub-parameters exist. If more than one sub-parameters with given ID
096: * found, the method should throw an {@link IllegalArgumentException}.
097: * @param id ID of sub-parameter to look for
098: * @return sub-parameter with given ID
099: */
100: Parameter getSubParameter(String id);
101:
102: /**
103: * @param id ID of sub-parameter to look for
104: * @return collection of all sub-parameters with given ID
105: */
106: Collection<Parameter> getSubParameters(String id);
107:
108: /**
109: * @return extension this parameter belongs to
110: */
111: Extension getDeclaringExtension();
112:
113: /**
114: * Returns definition for this extension parameter.
115: * May return <code>null</code> for "invalid" parameters.
116: * @return parameter definition or <code>null</code>, if this parameter
117: * is "invalid"
118: */
119: ParameterDefinition getDefinition();
120:
121: /**
122: * @return parameter, of which this one is child or <code>null</code> if
123: * this is top level parameter
124: */
125: Parameter getSuperParameter();
126:
127: /**
128: * Returns "typed" value of parameter. If this parameter is invalid or
129: * is not of type {@link ParameterType#STRING}, this method
130: * should throw an {@link UnsupportedOperationException}.
131: * @return value as String object
132: */
133: String valueAsString();
134:
135: /**
136: * Returns "typed" value of parameter. If this parameter is invalid or
137: * is not of type {@link ParameterType#BOOLEAN}, this method
138: * should throw an {@link UnsupportedOperationException}.
139: * @return value as Boolean object
140: */
141: Boolean valueAsBoolean();
142:
143: /**
144: * Returns "typed" value of parameter. If this parameter is invalid or
145: * is not of type {@link ParameterType#NUMBER}, this method
146: * should throw an {@link UnsupportedOperationException}.
147: * @return value as Number object
148: */
149: Number valueAsNumber();
150:
151: /**
152: * Returns "typed" value of parameter. If this parameter is invalid or
153: * is not of type {@link ParameterType#DATE}, {@link ParameterType#TIME}
154: * or {@link ParameterType#DATE_TIME}, this method should throw an
155: * {@link UnsupportedOperationException}.
156: * @return value as Date object
157: */
158: Date valueAsDate();
159:
160: /**
161: * Returns "typed" value of parameter. If this parameter is invalid or
162: * is not of type {@link ParameterType#PLUGIN_ID}, this
163: * method should throw an {@link UnsupportedOperationException}.
164: * @return value as PluginDescriptor object
165: */
166: PluginDescriptor valueAsPluginDescriptor();
167:
168: /**
169: * Returns "typed" value of parameter. If this parameter is invalid or
170: * is not of type {@link ParameterType#EXTENSION_POINT_ID},
171: * this method should throw an {@link UnsupportedOperationException}.
172: * @return value as ExtensionPoint object
173: */
174: ExtensionPoint valueAsExtensionPoint();
175:
176: /**
177: * Returns "typed" value of parameter. If this parameter is invalid or
178: * is not of type {@link ParameterType#EXTENSION_ID}, this
179: * method should throw an {@link UnsupportedOperationException}.
180: * @return value as Extension object
181: */
182: Extension valueAsExtension();
183:
184: /**
185: * Returns "typed" value of parameter. If this parameter is invalid or
186: * is not of type {@link ParameterType#RESOURCE}, this
187: * method should throw an {@link UnsupportedOperationException}.
188: * @return value as absolute or relative URL as specified in manifest
189: */
190: URL valueAsUrl();
191:
192: /**
193: * Returns "typed" value of parameter. If this parameter is invalid or
194: * is not of type {@link ParameterType#RESOURCE}, this
195: * method should throw an {@link UnsupportedOperationException}.
196: * @param pathResolver path resolver to make URL absolute
197: * @return value as absolute URL
198: */
199: URL valueAsUrl(PathResolver pathResolver);
200: }
201: }
|