/*
 * 
 * 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.outrigger;

import net.jini.id.Uuid;

/**
 * Methods that log an operation.  These are used
 * when writing to the store. <p>
 *
 * The <code>writeOp</code> and <code>takeOp</code> methods can
 * be called under a transaction. For these methods an in-progress
 * transaction is indicated by a non-null <code>txnId</code> parameter.
 * The <code>txnId</code> is an identifier for a transaction.
 * Each unique transaction must have a unique identifier and all
 * write or take operations under the same transaction should
 * use the same identifier. The store does not interpret the
 * identifier in any way. <p>
 *
 * <i>Note: Because the transaction identifier
 * must be unique, it can not be <code>ServerTransaction.id</code>.
 * Instead this identifier is the <code>Txn</code> ID. </i> <p>
 *
 * When a transaction is closed, the <code>prepareOp</code>,
 * <code>commitOp</code>, and <code>abortOp</code> methods are
 * passed the identifier (<code>txnId</code>) for that transaction. If
 * <code>prepareOp</code> is called and there is a restart, the
 * <code>txnId</code> passed to the write and take operations will
 * be passed back to the server via the <code>Recover.recoverWrite</code>
 * and <code>Recover.recoverTake</code> methods. Likewise the same
 * identifier will be passed to <code>Recover.recoverTransaction</code>.
 *
 * @see Store
 * @see Recover
 *
 * @author Sun Microsystems, Inc.
 *
 */
public interface LogOps {

    /**
     * Log a server boot (first time start or any reactivation).
     *
     * @see Recover#recoverSessionId
     *
     * @param time stamp for this boot
     *
     * @param sessionId of this boot
     */
    void bootOp(long time, long sessionId);

    /**
     * Log an update to the join state
     *
     * @see Recover#recoverJoinState
     *
     * @param state to be logged
     *
     */
    void joinStateOp(StorableObject state);

    /**
     * Log a <code>write</code> operation. If the operation was
     * performed under a transaction the <code>txnId</code> is
     * the identifier for that transaction.
     *
     * @see Recover#recoverWrite
     *
     * @param entry to be logged
     *
     * @param txnId transaction identifier or <code>null</code> if
     *        no transaction is active for this write
     */
    void writeOp(StorableResource entry, Long txnId);

    /**
     * Log a <code>take</code> operation. If the operation was
     * performed under a transaction the <code>txnId</code> is
     * the identifier for that transaction.
     *
     * @see Recover#recoverTake
     *
     * @param cookie ID identifying the entry target to be taken
     *
     * @param txnId transaction identifier or <code>null</code> if
     *        no transaction is active for this take
     */
    void takeOp(Uuid cookie, Long txnId);

    /**
     * Log a <code>notify</code> operation.  Notifications under
     * transactions are lost at the end of the transaction, so the
     * only ones that are logged are those that are under no
     * transaction.
     *
     * @see Recover#recoverRegister
     *
     * @param registration to be logged
     *
     * @param template associated with this registration 
     */
    void registerOp(StorableResource registration, StorableObject template);

    /**
     * Log a <code>renew</code> operation.  We use the expiration, not
     * the extension, because we don't want to calculate the
     * expiration relative to when we read the log -- we want to use
     * the exact expiration granted.
     *
     * @see StoredResource
     *
     * @param cookie ID of the entry or registration associated with this
     *               renew
     *
     * @param expiration time 
     */
    void renewOp(Uuid cookie, long expiration);

    /**
     * Log a <code>cancel</code> and entry or registration. The entry or
     * registration associated with <code>cookie</code> will no longer
     * be recoverable and may be removed from the log records.
     *
     * @param cookie ID of the entry or registration to cancel
     * @param expired is true if the cancel was due to a lease expiration
     */
    void cancelOp(Uuid cookie, boolean expired);

    /**
     * Log a transaction <code>prepare</code>. If there is a restart
     * before either <code>commitOp</code> or <code>abortOp</code> is
     * called for the transaction identified by <code>txnId</code>,
     * all write and take operations associated with <code>txnId</code>
     * will be recovered and <code>Recover.recoverTransaction</code>
     * called with the the same <code>txnId</code>.
     *
     * @see Recover#recoverTransaction
     *
     * @param txnId identifier of the transaction to be prepared
     *
     * @param transaction object associated with this transaction
     */
    void prepareOp(Long txnId, StorableObject transaction);

    /**
     * Log a transaction <code>commit</code> or
     * <code>prepareAndCommit</code>.  The store will commit the write
     * and take operations associated with <code>txnId</code>. A call
     * to <code>prepareOP</code> is not required for
     * <code>commitOp</code> to be called.
     *
     * @param txnId identifier of the transaction to be committed 
     */
    void commitOp(Long txnId);

    /**
     * Log a transaction <code>abort</code>. Any write and take operations
     * associated with <code>txnId</code> will no longer be recoverable
     * and may be removed from the log records.
     *
     * @param txnId identifier of the transaction to be aborted
     */
    void abortOp(Long txnId);

    /**
     * Log the <code>Uuid</code> that identifies the space as a whole.
     * @see Recover#recoverUuid
     * @param uuid The <code>Uuid</code> to be stored.
     */
    void uuidOp(Uuid uuid);
}
