001/*
002 * Copyright (c) 2006-2011 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     bstefanescu
011 */
012package org.nuxeo.ecm.core.event;
013
014import java.io.Serializable;
015import java.security.Principal;
016import java.util.Map;
017
018import org.nuxeo.ecm.core.api.CoreSession;
019
020/**
021 * An event context is describing the context in which a core event was raised.
022 * <p>
023 * You can subclass this class to implement more specialized event contexts like operations.
024 * <p>
025 * An event context is exposing information about the process the raised the event such as
026 * <ul>
027 * <li>the current core session.
028 * <li>the current principal.
029 * <li>the event data exposed as a list of arguments.
030 * <li>random properties that are associated with the event. These properties can be set by the event source or by any
031 * event listener that processes the event.
032 * </ul>
033 * To add more information you need to implement more specialized event contexts.
034 * <p>
035 * An event context also acts as an event factory. See {@link #newEvent(String)} and {@link #newEvent(String, int)}
036 * methods. Events created by an event context are automatically mapped to that context.
037 *
038 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
039 */
040public interface EventContext extends Serializable {
041
042    /**
043     * Gets event data. More objects can be associated with an event.
044     * <p>
045     * For this reason an array of objects is returned. This array is usually representing the arguments of the
046     * operation that raised the event.
047     *
048     * @return the event data
049     */
050    Object[] getArguments();
051
052    /**
053     * Gets the events properties.
054     * <p>
055     * Event properties are used to attach random information to an event context and can be set by the event source or
056     * by any listener that is processing the event. These properties usually serves to share data between the source
057     * and the listeners.
058     *
059     * @return the event properties
060     */
061    Map<String, Serializable> getProperties(); // TODO Serializable or Object?
062
063    /**
064     * Replaces all properties with the given ones. The given map is set as is - no copy occurs.
065     *
066     * @param properties the properties to use
067     */
068    void setProperties(Map<String, Serializable> properties);
069
070    /**
071     * Sets a event context property
072     *
073     * @param key the property key
074     * @param value the property value
075     */
076    void setProperty(String key, Serializable value);
077
078    /**
079     * Gets the named property from this context or null if not exists.
080     *
081     * @param key the property key
082     * @return the property, or null if it does not exist
083     */
084    Serializable getProperty(String key);
085
086    /**
087     * Tests whether or not the given property exists.
088     *
089     * @param key the property to test
090     * @return true if the named property was set, false otherwise
091     */
092    boolean hasProperty(String key);
093
094    /**
095     * Gets the current core session if any.
096     *
097     * @return the core session, or null if none
098     */
099    CoreSession getCoreSession();
100
101    /**
102     * Gets the current principal.
103     *
104     * @return the principal. Cannot be null.
105     */
106    Principal getPrincipal();
107
108    /**
109     * Sets the core session.
110     */
111    void setCoreSession(CoreSession session);
112
113    /**
114     * Sets the principal.
115     */
116    void setPrincipal(Principal principal);
117
118    /**
119     * Creates a new event in that context given the event name. The default flags for the event will be used.
120     *
121     * @param name the event name
122     * @return the event
123     * @see #newEvent(String, int)
124     */
125    Event newEvent(String name);
126
127    /**
128     * Creates a new event in that context given the event name. The given flags will be applied on the event.
129     *
130     * @param name the event name
131     * @param flags the event flags to use
132     * @return the event
133     */
134    Event newEvent(String name, int flags);
135
136    /**
137     * Returns the repository name associated to the event context, if any.
138     *
139     * @return the repository name
140     */
141    String getRepositoryName();
142
143    /**
144     * Sets the repository name. Only used if no CoreSession is available.
145     *
146     * @param repositoryName the repository name, or {@code null}
147     */
148    void setRepositoryName(String repositoryName);
149
150}