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}