/*
 * 
 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * The contents of this file are subject to the Sun Community Source
 * License v3.0/Jini Technology Specific Attachment v 1.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://wwws.sun.com/software/jini/licensing/SCSL3_JiniTSA1.html.
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Reference Code is Jini Technology Core Platform code, v2.0. The
 * Developer of the Reference Code is Sun Microsystems, Inc.
 * 
 * Contributor(s): Sun Microsystems, Inc.
 * 
 * The contents of this file comply with the Jini Technology Core
 * Platform Compatibility Kit, v2.0A.
 * 
 * Tester(s): Sun Microsystems, Inc.
 * 
 * Test Platform(s):
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Solaris(TM)SPARC/x86
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Linux (Intel x86)
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Windows (Intel Platform)
 * 
 */
package com.sun.jini.norm.event;

import java.rmi.MarshalledObject;
import net.jini.core.event.RemoteEvent;

/**
 * Factory interface for creating
 * <code>net.jini.core.event.RemoteEvent</code>.  An object of this
 * type is passed to each call of <code>EventType.sendEvent</code> and
 * is used by the <code>EventType</code> object to generate the
 * concrete <code>RemoteEvent</code> associated with a given event
 * occurrence on demand.  Providing a factory to <code>sendEvent</code>
 * instead of an actual <code>RemoteEvent</code> object allows
 * <code>eventType</code> object to send an event originally
 * intended for one listener to another.  
 *
 * @author Sun Microsystems, Inc.
 *
 * @see EventType 
 * @see EventType#sendEvent
 */
public interface EventFactory {
    /**
     * Create the concrete <code>RemoteEvent</code> for the associated
     * event occurrence.  Implementations should allow for the
     * possibility of being called with the same argument more that
     * once, especially the same eventID and seqNum.  The factory
     * should not mutate the event after it returns it. 
     * <p>
     * The caller will own no locks when calling this method.
     * @param eventID the event ID the new event should have
     * @param seqNum  the sequence number the new event object should have
     * @param handback the handback the new event object should have
     * @return the new event object
     */
    public RemoteEvent createEvent(long             eventID, 
				   long             seqNum, 
				   MarshalledObject handback);
}
