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