org.osgi.service.dmt.DmtEvent Maven / Gradle / Ivy

/*
 * Copyright (c) OSGi Alliance (2004, 2013). All Rights Reserved.
 * 
 * Licensed 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 org.osgi.service.dmt;

/**
 * Event class storing the details of a change in the tree. {@code DmtEvent} is
 * used by {@code DmtAdmin} to notify registered {@link DmtEventListener
 * EventListeners} services about important changes. Events are generated after
 * every successful DMT change, and also when sessions are opened or closed. If
 * a {@link DmtSession} is opened in atomic mode, DMT events are only sent when
 * the session is committed, when the changes are actually performed.
 * 
 * The {@code type} of the event describes the change that triggered the event
 * delivery. Each event carries the unique identifier of the session in which
 * the described change happened or -1 when the change originated outside a
 * session. The events describing changes in the DMT carry the list of affected
 * nodes. In case of {@link #COPIED} or {@link #RENAMED} events, the event
 * carries the list of new nodes as well.
 * 
 * @author $Id: 6ca0dc54a7e040668d4f97d158cd6799adbe3571 $
 */
public interface DmtEvent {

	/**
	 * Event type indicating nodes that were added.
	 */
	int	ADDED			= 0x01;

	/**
	 * Event type indicating nodes that were copied.
	 */
	int	COPIED			= 0x02;

	/**
	 * Event type indicating nodes that were deleted.
	 */
	int	DELETED			= 0x04;

	/**
	 * Event type indicating nodes that were renamed.
	 */
	int	RENAMED			= 0x08;

	/**
	 * Event type indicating nodes that were replaced.
	 */
	int	REPLACED		= 0x10;

	/**
	 * Event type indicating that a new session was opened.
	 */
	int	SESSION_OPENED	= 0x20;

	/**
	 * Event type indicating that a session was closed. This type of event is
	 * sent when the session is closed by the client or becomes inactive for any
	 * other reason (session timeout, fatal errors in business methods, etc.).
	 */
	int	SESSION_CLOSED	= 0x40;

	/**
	 * This method returns the type of this event.
	 * 
	 * @return the type of this event.
	 */
	int getType();

	/**
	 * This method returns the identifier of the session in which this event
	 * took place. The ID is guaranteed to be unique on a machine.
	 * 

	 * For events that do not result from a session, the session id is -1.
	 * 

	 * The availability of a session.id can also be check by using
	 * {@code getProperty()} with "session.id" as key.
	 * 
	 * @return the unique identifier of the session that triggered the event or
	 *         -1 if there is no session associated
	 */
	int getSessionId();

	/**
	 * This method can be used to query the subject nodes of this event. The
	 * method returns {@code null} for {@link #SESSION_OPENED} and
	 * {@link #SESSION_CLOSED}.
	 * 

	 * The method returns only those affected nodes that the caller has the GET
	 * permission for (or in case of {@link #COPIED} or {@link #RENAMED} events,
	 * where the caller has GET permissions for either the source or the
	 * destination nodes). Therefore, it is possible that the method returns an
	 * empty array. All returned URIs are absolute.
	 * 
	 * @return the array of affected nodes
	 * @see #getNewNodes()
	 */
	String[] getNodes();

	/**
	 * This method can be used to query the new nodes, when the type of the
	 * event is {@link #COPIED} or {@link #RENAMED}. For all other event types
	 * this method returns {@code null}.
	 * 

	 * The array returned by this method runs parallel to the array returned by
	 * {@link #getNodes()}, the elements in the two arrays contain the source
	 * and destination URIs for the renamed or copied nodes in the same order.
	 * All returned URIs are absolute.
	 * 

	 * This method returns only those nodes where the caller has the GET
	 * permission for the source or destination node of the operation.
	 * Therefore, it is possible that the method returns an empty array.
	 * 
	 * @return the array of newly created nodes
	 */
	String[] getNewNodes();

	/**
	 * This method can be used to query the names of all properties of this
	 * event.
	 * 
	 * The returned names can be used as key value in subsequent calls to
	 * {@link #getProperty(String)}.
	 * 
	 * @return the array of property names
	 * @see #getProperty(String)
	 * @since 2.0
	 */
	String[] getPropertyNames();

	/**
	 * This method can be used to get the value of a single event property.
	 * 
	 * @param key the name of the requested property
	 * @return the requested property value or null, if the key is not contained
	 *         in the properties
	 * @see #getPropertyNames()
	 * @since 2.0
	 */
	Object getProperty(String key);
}