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.rmi.dgc.VMID;
016
017/**
018 * An ordered set of events raised during an user operation.
019 * <p>
020 * The bundle is used collects any events that is raised during an user operation. The bundle will be send after the
021 * operation commit to any registered {@link PostCommitEventListener}.
022 * <p>
023 * The bundle implementation is free to ignore some events. This is the case for events marked as inline or for
024 * duplicate events.
025 *
026 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
027 */
028public interface EventBundle extends Iterable<Event>, Serializable {
029
030    /**
031     * Gets the bundle name.
032     * <p>
033     * This is usually the first event repository name in the bundle but the implementation may decide to change this
034     * behavior.
035     *
036     * @return the bundle name. Can be null only if the bundle is empty.
037     */
038    String getName();
039
040    /**
041     * Adds an event in that bundle at the end of the list.
042     * <p>
043     * The bundle implementation must ignore redundant events and events marked as inline.
044     *
045     * @param event the event to append.
046     */
047    void push(Event event);
048
049    /**
050     * Gets the first event in that bundle.
051     *
052     * @return the first event. Can be null if the bundle is empty
053     */
054    Event peek();
055
056    /**
057     * Tests whether or not this bundle is empty.
058     */
059    boolean isEmpty();
060
061    /**
062     * Gets the size of that bundle.
063     *
064     * @return the number of events in that bundle
065     */
066    int size();
067
068    /**
069     * Tests whether or not this event bundle was created on a remote machine.
070     *
071     * @return true if the event bundle was fired from a remote machine, false otherwise
072     */
073    boolean hasRemoteSource();
074
075    /**
076     * Returns the VMID of the JVM where the bundle was created.
077     */
078    VMID getSourceVMID();
079
080    /**
081     * Check is bundle contains the specified event.
082     */
083    boolean containsEventName(String eventName);
084
085}