001 /*
002 * Copyright 2008-2016 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 javax.annotation.Nonnull;
019 import javax.annotation.Nullable;
020 import java.util.Collections;
021 import java.util.List;
022 import java.util.Set;
023
024 /**
025 * Helper class capable of dealing with artifacts and their handlers.
026 *
027 * @author Andres Almiray
028 * @since 2.0.0
029 */
030 @SuppressWarnings("rawtypes")
031 public interface ArtifactManager {
032 List<GriffonClass> EMPTY_GRIFFON_CLASS_LIST = Collections.emptyList();
033
034 /**
035 * Registers an ArtifactHandler by type.<p>
036 * Should call initialize() on the handler.
037 *
038 * @param handler an ArtifactHandler
039 */
040 void registerArtifactHandler(@Nonnull ArtifactHandler handler);
041
042 /**
043 * Removes an ArtifactHandler by type.
044 *
045 * @param handler an ArtifactHandler
046 */
047 void unregisterArtifactHandler(@Nonnull ArtifactHandler handler);
048
049 /**
050 * Reads the artifacts definitions file from the classpath.<p>
051 * Should call initialize() on artifact handlers if there are any
052 * registered already.
053 */
054 void loadArtifactMetadata();
055
056 /**
057 * Finds an artifact by name and type.<p>
058 * Example: findGriffonClass("Book", "controller") will return an
059 * artifact class that describes BookController.
060 *
061 * @param name the name of the artifact, e.g. 'Book'
062 * @param type the type of the artifact, e.g. 'controller'
063 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
064 */
065 @Nullable
066 GriffonClass findGriffonClass(@Nonnull String name, @Nonnull String type);
067
068 /**
069 * Finds an artifact by class and type.<p>
070 * Example: findGriffonClass(BookController, "controller") will return an
071 * artifact class that describes BookController.
072 *
073 * @param clazz the name of the artifact, e.g. com.acme.BookController
074 * @param type the type of the artifact, e.g. 'controller'
075 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
076 */
077 @Nullable
078 GriffonClass findGriffonClass(@Nonnull Class<? extends GriffonArtifact> clazz, @Nonnull String type);
079
080 /**
081 * Finds an artifact by class.<p>
082 * Example: findGriffonClass(aBookControllerInstance) will return an
083 * artifact class that describes BookController.
084 *
085 * @param artifact an artifact instance
086 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
087 */
088 @Nullable
089 <A extends GriffonArtifact> GriffonClass findGriffonClass(@Nonnull A artifact);
090
091 /**
092 * Finds an artifact by class.<p>
093 * Example: findGriffonClass(BookController) will return an
094 * artifact class that describes BookController.
095 *
096 * @param clazz a Class instance
097 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
098 */
099 @Nullable
100 GriffonClass findGriffonClass(@Nonnull Class<? extends GriffonArtifact> clazz);
101
102 /**
103 * Finds an artifact by name.<p>
104 * Example: findGriffonClass("BookController") will return an
105 * artifact class that describes BookController.
106 *
107 * @param fqClassName full qualified class name
108 * @return the GriffonClass associated with the artifact is there's a match, null otherwise.
109 */
110 @Nullable
111 GriffonClass findGriffonClass(@Nonnull String fqClassName);
112
113 /**
114 * Finds all artifacts of an specific type.<p>
115 * Example: getClassesOfType("controller") will return all
116 * artifact classes that describe controllers.
117 *
118 * @param type an artifact type, e.g. 'controller'
119 * @return a List of matching artifacts or an empty List if no match. Never returns null.
120 */
121 @Nonnull
122 List<GriffonClass> getClassesOfType(@Nonnull String type);
123
124 /**
125 * Finds all supported artifact types.<p>
126 *
127 * @return a Set of all available artifact types. Never returns null.
128 * @since 2.2.0
129 */
130 @Nonnull
131 Set<String> getAllTypes();
132
133 /**
134 * Finds all artifact classes.<p>
135 *
136 * @return a List of all available GriffonClass instances. Never returns null.
137 */
138 @Nonnull
139 List<GriffonClass> getAllClasses();
140
141 /**
142 * Creates a new instance of the specified class and type.<br/>
143 * Triggers the ApplicationEvent.NEW_INSTANCE with the following parameters
144 * <ul>
145 * <li>clazz - the Class of the object</li>
146 * <li>instance -> the object that was created</li>
147 * </ul>
148 *
149 * @param griffonClass the GriffonClass for which an instance must be created
150 * @return a newly instantiated object of type <tt>clazz</tt>. Implementations must be sure
151 * to trigger an event of type ApplicationEvent.NEW_INSTANCE.
152 * @throws griffon.exceptions.ArtifactNotFoundException if there's no artifact configured
153 * matching the given criteria
154 */
155 @Nonnull
156 <A extends GriffonArtifact> A newInstance(@Nonnull GriffonClass griffonClass);
157
158 /**
159 * Creates a new instance of the specified class and type.<br/>
160 * Triggers the ApplicationEvent.NEW_INSTANCE with the following parameters
161 * <ul>
162 * <li>clazz - the Class of the object</li>
163 * <li>instance -> the object that was created</li>
164 * </ul>
165 *
166 * @param clazz the Class for which an instance must be created
167 * @return a newly instantiated object of type <tt>clazz</tt>. Implementations must be sure
168 * to trigger an event of type ApplicationEvent.NEW_INSTANCE.
169 * @throws griffon.exceptions.ArtifactNotFoundException if there's no artifact configured
170 * matching the given criteria
171 */
172 @Nonnull
173 <A extends GriffonArtifact> A newInstance(@Nonnull Class<A> clazz);
174 }
|