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