ArtifactHandler.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.Map;
023 
024 /**
025  * The ArtifactHandler interface's purpose is to allow the analysis of conventions within a Griffon application.<p>
026  * An artifact is represented by the GriffonClass interface and this interface provides methods that allow artifacts to
027  * be identified, created and initialized.
028  *
029  @author Andres Almiray
030  */
031 public interface ArtifactHandler<A extends GriffonArtifact> {
032     @Nonnull
033     Class<A> getArtifactType();
034 
035     /**
036      * Get the type of artifact this handler processes.
037      *
038      @return the type of artifacts this handler can handle, e.g. 'service'
039      */
040     @Nonnull
041     String getType();
042 
043     /**
044      * Get the trailing suffix that identifies the artifact.<p>
045      * May be empty but non-null.
046      *
047      @return the trailing name suffix (if any), e.g. 'Service'
048      */
049     @Nonnull
050     String getTrailing();
051 
052     /**
053      * Returns true if the target Class is a class artifact
054      * handled by this object.
055      *
056      @param clazz a Class instance
057      @return true if this handler is capable of handling the artifact class, false otherwise.
058      */
059     boolean isArtifact(@Nonnull Class<A> clazz);
060 
061     /**
062      * Returns true if the target GriffonClass is a class artifact
063      * handled by this object.
064      *
065      @param clazz a GriffonClass instance
066      @return true if this handler is capable of handling the clazz parameter, false otherwise.
067      */
068     boolean isArtifact(@Nonnull GriffonClass clazz);
069 
070     /**
071      * Initializes the handler with a collection of all available
072      * classes this handler can process.<p>
073      * This is a good time to pre-emptively instantiate beans or
074      * perform additional checks on artifacts.
075      *
076      @param classes an array of all classes this handler should manage
077      */
078     void initialize(@Nonnull Class<A>[] classes);
079 
080     /**
081      * Returns the set of all artifact classes this handler manages.
082      *
083      @return an array of all GriffonClasses managed by this handler. Never returns null.
084      */
085     @Nonnull
086     GriffonClass[] getClasses();
087 
088     /**
089      * Finds an artifact by its property name.<p>
090      * Examples: findClassfor("fooService") returns an artifact class
091      * that can handle FooService.<p>
092      <p>
093      * Should {@code propertyName} contain any dots then the portion
094      * after the last dot will be considered only.
095      *
096      @param propertyName the property representation of an artifact, e.g. 'fooService'
097      @return a GriffonClass instance if there's a match, null otherwise.
098      */
099     @Nullable
100     GriffonClass findClassFor(@Nonnull String propertyName);
101 
102     /**
103      * Finds an artifact if the target {@code clazz} is handled by this
104      * ArtifactHandler.<p>
105      *
106      @param clazz a class object, i.e, BookController
107      @return a GriffonClass that can handle the target class or null
108      * if the clazz is not handled by this ArtifactHandler.
109      */
110     @Nullable
111     GriffonClass getClassFor(@Nonnull Class<A> clazz);
112 
113     /**
114      * Finds an artifact by class name if it represents a class that
115      * is handled by this ArtifactHandler.<p>
116      *
117      @param fqnClassName a full qualified class name, i.e, "book.BookController"
118      @return a GriffonClass that can handle the target class or null
119      * if the clazz is not handled by this ArtifactHandler.
120      */
121     @Nullable
122     GriffonClass getClassFor(@Nonnull String fqnClassName);
123 
124     @Nonnull
125     GriffonClass newGriffonClassInstance(@Nonnull Class<A> clazz);
126 
127     @Nonnull
128     Map<String, GriffonClass> getClassesByName();
129 }