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