ArtifactManager.java
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 }