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: * $Header:$
018: */
019: package org.apache.beehive.controls.api.assembly;
020:
021: import java.io.File;
022: import java.lang.annotation.Annotation;
023: import java.lang.reflect.Method;
024: import java.util.Map;
025: import java.util.Set;
026:
027: import com.sun.mirror.apt.Messager;
028:
029: /**
030: * Control assemblers are passed a ControlAssemblyContext at the time they are
031: * invoked; the context allows the assemblers to interact with their external
032: * environment (checking files, side-effecting deployment descriptors, emitting
033: * code parameterized by the specifics of the control extension, etc).
034: *
035: * Beehive provides ControlAssemblyContext implementations that expose the
036: * standard environments of J2EE applications and modules. Vendor-specific
037: * implementations may provide access to their specific environment information,
038: * such as vendor-specific descriptors, via definition and implementation
039: * of additional interfaces. ControlAssemblers should use reflection to
040: * determine if the ControlAssemblyContext implementation they are passed
041: * supports a particular set of environment features.
042: */
043: public interface ControlAssemblyContext {
044: /**
045: * Providers of ControlAssemblyContext implementations MUST implement
046: * Factory and newInstance to return their implementation.
047: */
048: interface Factory {
049: /**
050: * Creates a new instance of a ControlAssemblyContext implementation.
051: *
052: * @param controlIntfOrExt public interface/extension of the control
053: * type being assembled
054: * @param bindings map of control implementation bindings, null
055: * means use defaults.
056: * @param clients set of clients that use this control type.
057: * @param moduleRoot file root of the J2EE module containing the
058: * control clients to be assembled
059: * @param moduleName name of the J2EE module containing the
060: * control clients to be assembled
061: * @param srcOutputRoot file root of a location where assemblers
062: * should output any sources they create that
063: * may need further processing before use.
064: * @return a new instance of a ControlAssemblyContext implementation
065: */
066: ControlAssemblyContext newInstance(Class controlIntfOrExt,
067: Map<String, String> bindings, Set<String> clients,
068: File moduleRoot, String moduleName, File srcOutputRoot)
069: throws ControlAssemblyException;
070: }
071:
072: /**
073: * Providers of ControlAssemblyContext implementations may implement
074: * EJBModule to provide access to an EJB module environment.
075: */
076: interface EJBModule {
077: // TODO: Provide more abstract helpers for common tasks.
078: // E.g. addResourceRef().
079:
080: File getEjbJarXml();
081: }
082:
083: /**
084: * Providers of ControlAssemblyContext implementations may implement
085: * WebAppModule to provide access to a webapp module environment.
086: */
087: interface WebAppModule {
088: File getWebXml();
089: }
090:
091: /**
092: * Providers of ControlAssemblyContext implementations may implement
093: * EntAppModule to provide access to an enterprise application module
094: * environment.
095: */
096: interface EntAppModule {
097: File getApplicationXml();
098: }
099:
100: /**
101: * @return the interface type of the control being assembled (annotated
102: * w/ ControlExtension or ControlInterface)
103: */
104: Class getControlType();
105:
106: /**
107: * @return the most derived interface of the control being assembled that
108: * is annotated with ControlInterface (may return the same as
109: * getControlType() if the control type is non-extended)
110: */
111: Class getMostDerivedControlInterface();
112:
113: /**
114: * @return an annotation on the interface returned by
115: * getControlType()
116: */
117: <T extends Annotation> T getControlAnnotation(
118: Class<T> annotationClass);
119:
120: /**
121: * @return an annotation on a method on the interface
122: * returned by getControlType()
123: */
124: <T extends Annotation> T getControlMethodAnnotation(
125: Class<T> annotationClass, Method m)
126: throws NoSuchMethodException;
127:
128: /**
129: * @return the defaultBinding member of the ControlInterface
130: */
131: String getDefaultImplClassName();
132:
133: /**
134: * @return the output directory into which "compilable" source should be output.
135: */
136: File getSrcOutputDir();
137:
138: /**
139: * @return the root of the module for which assembly is taking place.
140: */
141: File getModuleDir();
142:
143: /**
144: * @return the name of the module for which assembly is taking place.
145: */
146: String getModuleName();
147:
148: /**
149: * @return the set of clients (by class name) which use the control type
150: */
151: Set<String> getClients();
152:
153: /**
154: * @return a Messager implementation that can be used to emit diagnostics during the
155: * assembly process.
156: */
157: Messager getMessager();
158:
159: /**
160: * @return true if the assembly process reported errors via the Messager
161: */
162: boolean hasErrors();
163: }
|