javax.enterprise.inject.spi.ObserverMethod Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javaee-api Show documentation
There is a newer version: 8.0-6
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package javax.enterprise.inject.spi;

import java.lang.annotation.Annotation;
import java.lang.reflect.Type;
import java.util.Set;

import javax.enterprise.event.Reception;
import javax.enterprise.event.TransactionPhase;

/**
 * ObserverMethod is the SPI to handle an observer method, which is 
 * an event consumer for an event of the given type T. An instance of
 * ObserverMethod exists for every observer method of every enabled bean. 
 * 
 * A class may have n observer methods.
 * Each observer method must have a void return value and exactly one parameter
 * which defines which event it {@code javax.enterprise.event.Observes}.
 * The observed event may be further specified by using an optional Qualifier. 
 * 
 * Sample:
 *  * public class UserHandler 
 * {
 *   public void afterUserLogin(@Observes UserLoginEvent userHasLoggedIn) 
 *   {
 *     // prepare some data for the user, ...
 *     int userId = userHadLoggedIn.getUserId();
 *     ...
 *   }
 *   
 *   public void afterAdminLogin(@Observes @Admin UserLoginEvent userHasLoggedIn) 
 *   {
 *     // prepare stuff for the admin user
 *     ...
 *   }
 *   
 *   public void afterUserLogout(@Observes UserLogoutEvent userHasLoggedOut) 
 *   {
 *     // cleanup afterwards 
 *     ...
 *   }
 * }
 * 
 *  
 * @param  the event which should be observed
 * @see javax.enterprise.event.Observes
 */
public interface ObserverMethod extends Prioritized
{
    /**
     * The default Priority of any ObserverMethod without a @Priority annotation.
     */
    int DEFAULT_PRIORITY = 2500;

    Class getBeanClass();
    
    /**
     * @return the type of the observed event
     */
    Type getObservedType();
    
    /**
     * @return the defined Qualifiers plus {@code javax.enterprise.inject.Any}
     */
    Set getObservedQualifiers();
    
    /**
     * @return either {@code Reception#IF_EXISTS} if the observed method must only be called if an instance
     * of the bean which defines the observer method aready exists in the specified context or {@code Reception#ALWAYS}. 
     */
    Reception getReception();
    
    /**
     * @return the appropriate {@code TransactionPhase} for a transactional observer method or
     * {@code TransactionPhase#IN_PROGRESS} otherwise. 
     */
    TransactionPhase getTransactionPhase();

    /**
     * will actually call the underlying observer method
     * @param event
     */
    default void notify(T event)
    {
        // empty by default
    }

    /**
     * Call the observer method with the given eventContext.
     * @param eventContext
     */
    default void notify(EventContext eventContext)
    {
        if (eventContext != null)
        {
            notify(eventContext.getEvent());
        }
    }

   /**
    * @return Whether or not this observer method is an async observer.  defaults to false for compatibility
    */
    default boolean isAsync()
    {
        return false;
    }

    /**
     * Only synchronous ObserverMethods can be ordered!
     *
     * @return The @Priority of this ObserverMethod
     */
    default int getPriority()
    {
        return DEFAULT_PRIORITY;
    }


}