1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one
    3    * or more contributor license agreements.  See the NOTICE file
    4    * distributed with this work for additional information
    5    * regarding copyright ownership.  The ASF licenses this file
    6    * to you under the Apache License, Version 2.0 (the
    7    * "License"); you may not use this file except in compliance
    8    * with the License.  You may obtain a copy of the License at
    9    *
   10    * http://www.apache.org/licenses/LICENSE-2.0
   11    *
   12    * Unless required by applicable law or agreed to in writing,
   13    * software distributed under the License is distributed on an
   14    * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   15    * KIND, either express or implied.  See the License for the
   16    * specific language governing permissions and limitations
   17    * under the License.
   18    */
   19   package javax.enterprise.inject.spi;
   20   
   21   import java.util.Set;
   22   
   23   import javax.enterprise.context.spi.CreationalContext;
   24   
   25   /**
   26    * Provides a generic operation for producing an instance of a type.
   27    * 
   28    * @version $Rev: 815435 $ $Date: 2009-09-15 21:18:44 +0300 (Tue, 15 Sep 2009) $
   29    * 
   30    * <T> bean type
   31    */
   32   public interface Producer<T> 
   33   {
   34   	/**
   35   	 * Its result depends on bean type.
   36   	 * 
   37   	 * <p>
   38   	 * 
   39   	 * <ul>
   40   	 * 
   41   	 * 	<li><b>Bean Class</b> : It calls the constructor annotated with {@link Initializer} if it 
   42   	 * exists, or the constructor with no parameters otherwise.</li>
   43   	 *  
   44   	 *  <li><b>Producer Method or Field</b> : Calls the producer method on, 
   45   	 *  or accesses the producer field of, a contextual instance of the most 
   46   	 *  specialized bean that specializes the bean that declares the producer method</li>
   47   	 * 
   48   	 * </ul>
   49   	 * 
   50   	 * </p>
   51   
   52   	 * @param creationalContext creational context
   53   	 * 
   54   	 * @return an instance of bean
   55   	 */
   56   	public T produce(CreationalContext<T> creationalContext);
   57   	
   58   	/**
   59   	 * Its result depends on bean type.
   60   	 * <p>
   61   	 * <ul>
   62   	 * 	<li><b>Bean Class</b> : Does nothing.</li>
   63   	 *  <li><b>Producer Method</b> : Calls disposer method or any other cleanup.
   64   	 * </ul>
   65   	 * </p>
   66   	 * 
   67   	 * @param instance dispose istance
   68   	 */
   69   	public void dispose(T instance);
   70   	
   71   	/**
   72   	 * Its result depends on bean type.
   73   	 * 
   74   	 * <p>
   75   	 * 
   76   	 * <ul>
   77   	 * 	<li><b>Bean Class</b> : Returns the set of InjectionPoint objects representing all injected fields, 
   78   	 * bean constructor parameters and initializer method parameters.</li>
   79   	 *
   80   	 *  <li><b>Producer Method</b> : Returns the set of InjectionPoint objects 
   81   	 *  representing all parameters of the producer method.</li>
   82   	 *  
   83   	 * </ul>
   84   	 * 
   85   	 * </p>
   86   	 * 
   87   	 * @return set of injection points
   88   	 */
   89   	public Set<InjectionPoint> getInjectionPoints();
   90   	
   91   	
   92   }