001 /*
002 * Copyright 2008-2015 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package griffon.core.artifact;
017
018 import griffon.core.ShutdownHandler;
019 import griffon.core.injection.Injector;
020
021 import javax.annotation.Nonnull;
022 import javax.annotation.Nullable;
023 import java.util.Collections;
024 import java.util.List;
025 import java.util.Set;
026
027 /**
028 * Helper class capable of dealing with artifacts and their handlers.
029 *
030 * @author Andres Almiray
031 * @since 2.0.0
032 */
033 @SuppressWarnings("rawtypes")
034 public interface ArtifactManager extends ShutdownHandler {
035 List<GriffonClass> EMPTY_GRIFFON_CLASS_LIST = Collections.emptyList();
036
037 /**
038 * Registers an ArtifactHandler by type.<p>
039 * Should call initialize() on the handler.
040 *
041 * @param handler an ArtifactHandler
042 */
043 void registerArtifactHandler(@Nonnull ArtifactHandler handler);
044
045 /**
046 * Removes an ArtifactHandler by type.
047 *
048 * @param handler an ArtifactHandler
049 */
050 void unregisterArtifactHandler(@Nonnull ArtifactHandler handler);
051
052 /**
053 * Reads the artifacts definitions file from the classpath.<p>
054 * Should call initialize() on artifact handlers if there are any
055 * registered already.
056 */
057 void loadArtifactMetadata(@Nonnull Injector<?> injector);
058
059 /**
060 * Finds an artifact by name and type.<p>
061 * Example: findGriffonClass("Book", "controller") will return an
062 * artifact class that describes BookController.
063 *
064 * @param name the name of the artifact, e.g. 'Book'
065 * @param type the type of the artifact, e.g. 'controller'
066 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
067 */
068 @Nullable
069 GriffonClass findGriffonClass(@Nonnull String name, @Nonnull String type);
070
071 /**
072 * Finds an artifact by class and type.<p>
073 * Example: findGriffonClass(BookController, "controller") will return an
074 * artifact class that describes BookController.
075 *
076 * @param clazz the name of the artifact, e.g. com.acme.BookController
077 * @param type the type of the artifact, e.g. 'controller'
078 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
079 */
080 @Nullable
081 GriffonClass findGriffonClass(@Nonnull Class<? extends GriffonArtifact> clazz, @Nonnull String type);
082
083 /**
084 * Finds an artifact by class.<p>
085 * Example: findGriffonClass(aBookControllerInstance) will return an
086 * artifact class that describes BookController.
087 *
088 * @param artifact an artifact instance
089 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
090 */
091 @Nullable
092 <A extends GriffonArtifact> GriffonClass findGriffonClass(@Nonnull A artifact);
093
094 /**
095 * Finds an artifact by class.<p>
096 * Example: findGriffonClass(BookController) will return an
097 * artifact class that describes BookController.
098 *
099 * @param clazz a Class instance
100 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
101 */
102 @Nullable
103 GriffonClass findGriffonClass(@Nonnull Class<? extends GriffonArtifact> clazz);
104
105 /**
106 * Finds an artifact by name.<p>
107 * Example: findGriffonClass("BookController") will return an
108 * artifact class that describes BookController.
109 *
110 * @param fqClassName full qualified class name
111 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
112 */
113 @Nullable
114 GriffonClass findGriffonClass(@Nonnull String fqClassName);
115
116 /**
117 * Finds all artifacts of an specific type.<p>
118 * Example: getClassesOfType("controller") will return all
119 * artifact classes that describe controllers.
120 *
121 * @param type an artifact type, e.g. 'controller'
122 * @return a List of matching artifacts or an empty List if no match. Never returns null.
123 */
124 @Nonnull
125 List<GriffonClass> getClassesOfType(@Nonnull String type);
126
127 /**
128 * Finds all supported artifact types.<p>
129 *
130 * @return a Set of all available artifact types. Never returns null.
131 * @since 2.2.0
132 */
133 @Nonnull
134 Set<String> getAllTypes();
135
136 /**
137 * Finds all artifact classes.<p>
138 *
139 * @return a List of all available GriffonClass instances. Never returns null.
140 */
141 @Nonnull
142 List<GriffonClass> getAllClasses();
143
144 /**
145 * Creates a new instance of the specified class and type.<br/>
146 * Triggers the ApplicationEvent.NEW_INSTANCE with the following parameters
147 * <ul>
148 * <li>clazz - the Class of the object</li>
149 * <li>instance -> the object that was created</li>
150 * </ul>
151 *
152 * @param griffonClass the GriffonClass for which an instance must be created
153 * @return a newly instantiated object of type <tt>clazz</tt>. Implementations must be sure
154 * to trigger an event of type ApplicationEvent.NEW_INSTANCE.
155 * @throws griffon.exceptions.ArtifactNotFoundException
156 * if there's no artifact configured
157 * matching the given criteria
158 */
159 @Nonnull
160 <A extends GriffonArtifact> A newInstance(@Nonnull GriffonClass griffonClass);
161
162 /**
163 * Creates a new instance of the specified class and type.<br/>
164 * Triggers the ApplicationEvent.NEW_INSTANCE with the following parameters
165 * <ul>
166 * <li>clazz - the Class of the object</li>
167 * <li>instance -> the object that was created</li>
168 * </ul>
169 *
170 * @param clazz the Class for which an instance must be created
171 * @return a newly instantiated object of type <tt>clazz</tt>. Implementations must be sure
172 * to trigger an event of type ApplicationEvent.NEW_INSTANCE.
173 * @throws griffon.exceptions.ArtifactNotFoundException
174 * if there's no artifact configured
175 * matching the given criteria
176 */
177 @Nonnull
178 <A extends GriffonArtifact> A newInstance(@Nonnull Class<A> clazz);
179 }
|