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