001    /*
002     * Copyright (c) OSGi Alliance (2005, 2008). All Rights Reserved.
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 org.osgi.service.event;
018    
019    /**
020     * Listener for Events.
021     * 
022     * <p>
023     * <code>EventHandler</code> objects are registered with the Framework service
024     * registry and are notified with an <code>Event</code> object when an event
025     * is sent or posted.
026     * <p>
027     * <code>EventHandler</code> objects can inspect the received
028     * <code>Event</code> object to determine its topic and properties.
029     * 
030     * <p>
031     * <code>EventHandler</code> objects must be registered with a service
032     * property {@link EventConstants#EVENT_TOPIC} whose value is the list of topics
033     * in which the event handler is interested.
034     * <p>
035     * For example:
036     * 
037     * <pre>
038     * String[] topics = new String[] {&quot;com/isv/*&quot;};
039     * Hashtable ht = new Hashtable();
040     * ht.put(EventConstants.EVENT_TOPIC, topics);
041     * context.registerService(EventHandler.class.getName(), this, ht);
042     * </pre>
043     * 
044     * Event Handler services can also be registered with an
045     * {@link EventConstants#EVENT_FILTER} service property to further filter the
046     * events. If the syntax of this filter is invalid, then the Event Handler must
047     * be ignored by the Event Admin service. The Event Admin service should log a
048     * warning.
049     * <p>
050     * Security Considerations. Bundles wishing to monitor <code>Event</code>
051     * objects will require <code>ServicePermission[EventHandler,REGISTER]</code>
052     * to register an <code>EventHandler</code> service. The bundle must also have
053     * <code>TopicPermission[topic,SUBSCRIBE]</code> for the topic specified in
054     * the event in order to receive the event.
055     * 
056     * @see Event
057     * 
058     * @ThreadSafe
059     * @version $Revision: 5673 $
060     */
061    public interface EventHandler {
062            /**
063             * Called by the {@link EventAdmin} service to notify the listener of an
064             * event.
065             * 
066             * @param event The event that occurred.
067             */
068            void handleEvent(Event event);
069    }