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