/*
Copyright 2002-2005 The Members of the OSS through Java(TM) Initiative.
All rights reserved. Use is subject to license terms.
*/
package javax.oss;


/**
 * This is the base interface for an event object in a JMS ObjectMessage payload.
 * <p>
 * If a JMS MessageListener receives such a message,
 * the following code will run:
 * <pre>
 * public void onMessage(Message msg) {
 *    ObjectMessage omsg = (ObjectMessage) msg;
 *    Event event = (Event) omsg.getObject();
 *    System.out.println("New event received from " + event.getApplicationDN());
 * }
 * </pre>
 *
  * @see AttributeAccess
 *
 * @author OSS through Java Initiative, Vincent Perrot Sun Microsystems Inc.
 * @version 1.2
 * @since March 2005
 * @ossj:event
 */
public interface Event extends java.io.Serializable, Cloneable,
        javax.oss.AttributeAccess {
    
    /**
     * Constant representing event attribute 'applicationDN'.
     */
    public final static String APPLICATION_DN = "applicationDN";
    
    /**
     * Constant representing event attribute 'eventTime'.
     */
    public final static String EVENT_TIME = "eventTime";
    
    /**
     * Constant representing event attribute 'managedObjectClass'.
     */
    //CR6250093
    public final static String MANAGED_OBJECT_CLASS = "managedObjectClass";
    
    /**
     * Constant representing event attribute 'managedObjectInstance'.
     */
    //CR6250093
    public final static String MANAGED_OBJECT_INSTANCE = "managedObjectInstance";
    
    /**
     * Deep copy this Event.
     *
     * @return deep copy of this Event.
     */
    public Object clone();
    
    /**
     * Returns the time that the event is published.
     *
     * @throws java.lang.IllegalArgumentException
     */
    public java.util.Date getEventTime();
    
    /**
     * Set the time that the event is published.
     *
     * @throws java.lang.IllegalArgumentException
     */
    public void setEventTime(java.util.Date time) throws java.lang.IllegalArgumentException;
    
    /**
     * Return the Distinguish Name (DN) of the application sending the event.
     * The format of this DN is described in
     * javax.oss.ManagedEntityKey.getApplicationDN()
     *
     * @see javax.oss.ManagedEntityKey
     * @throws java.lang.IllegalArgumentException
     * @return applicationDN.
     */
    public String getApplicationDN();
    
    /**
     * Set the application Distinguish Name for the Event
     *
     * @param applicationDN a string representation of the application DN
     *
     * @throws java.lang.IllegalArgumentException when the application DN is null.
     */
    public void setApplicationDN(String applicationDN) throws java.lang.IllegalArgumentException;
    
    /**
     * Gets the class name of the object instance where this event occurred.
     *
     * @return String The class name object instance.
     * @exception java.lang.IllegalStateException Is thrown if the attribute is supported,
     * and the attribute has not been populated.
     * @see #setManagedObjectClass
     */
    //CR6250093
    public String getManagedObjectClass() throws java.lang.IllegalStateException;
    
    /**
     * Sets the class name of the object instance that will issue this event.
     *
     * @param moc The class name of the object instance.
     * @exception java.lang.IllegalArgumentException Is thrown to report that
     * a bad argument was provided to the method.
     * @see #getManagedObjectClass
     */
    //CR6250093
    public void setManagedObjectClass( String moc) throws java.lang.IllegalArgumentException;
    
    /**
     * Gets the distinguished name of the object instance where this event occurred.
     *
     * @return String The distinguished name object instance.
     * @exception java.lang.IllegalStateException Is thrown if the attribute is supported,
     * and the attribute has not been populated.
     * @see #setManagedObjectInstance
     */
    //CR6250093
    public String getManagedObjectInstance() throws java.lang.IllegalStateException;
    
    /**
     * Sets the distinguished name of the object instance that will issue this event.
     *
     * @param moi The distinguished name of the object instance.
     * @exception java.lang.IllegalArgumentException Is thrown to report that
     * a bad argument was provided to the method.
     * @see #getManagedObjectInstance
     */
    //CR6250093
    public void setManagedObjectInstance( String moi) throws java.lang.IllegalArgumentException;
    
}
