jahiaeditablecontent.java

java 写的一个新闻发布系统

//
//                                   ____.
//                       __/\ ______|    |__/\.     _______
//            __   .____|    |       \   |    +----+       \
//    _______|  /--|    |    |    -   \  _    |    :    -   \_________
//   \\______: :---|    :    :           |    :    |         \________>
//           |__\---\_____________:______:    :____|____:_____\
//                                      /_____|
//
//                 . . . i n   j a h i a   w e   t r u s t . . .
//

package org.jahia.data;

import org.jahia.data.JahiaObject;
import org.jahia.utils.Semaphore;
import org.jahia.exceptions.JahiaException;


/**
 * The JahiaObject class is the root of all the user-editable object (like
 * pages, containers, fields, users, groups, rights, ...). It prevents multiple
 * simultaneous write access to an object's internal data, which might place
 * the object in an unconsistent state.<br/>
 * <br/>
 * There are three kind of locks on an object : read, update and write. The
 * read lock is not really a lock, but it indicates the object read calls are
 * active on the object. Write calls are not allowed while read calls are
 * active. The update lock notify the object a user has entered in an
 * updating/deleting process. During this process, other users are not allowed
 * to update or delete the object. This update lock doesn't prevent reading calls
 * nor writing calls. Writing the internal state of on object should be done
 * only and only after having requested the writing lock. Getting the writing lock
 * will prevent any reading and/or writing calls.<br/>
 * <br/>
 * Each time an update or delete popup is requested for a specfied object, the
 * update lock should be requested and the popup should be displayed only if this
 * lock is available. If it's not the case, a special message should inform the
 * user the object is not available yet, and a further attempt should be tried
 * later.<br/>
 * <br/>
 * The write access lock should be requested <b>only</b> when the new data (or deletion)
 * are ready to be written. Request the write lock only when the user submitted
 * his changes and these changes are processed (for valid checks, ...), and not
 * when the update/delete popup is displayed. The purpose is to minimize at
 * maximum the time the object is blocked for write access.<br/>
 * <br/>
 * <b>DON'T FORGET TO RELEASE THE LOCKS AFTER COMPLETION OF THE TASKS !</b><br/>
 * No check for deadlocks is done in this class, it's left to the developper.
 *
 * @author  Fulco Houkes
 * @version 1.0;
 */
public class JahiaEditableContent extends JahiaObject
{

    private boolean     mReadable;
    private int         mReadCounter;
    private Semaphore   mWriteLock;
    private Semaphore   mUpdateLock;


    //-------------------------------------------------------------------------
    public JahiaEditableContent ()
    {
        super();
        mReadable     = true;
        mReadCounter  = 0;
        mWriteLock    = new Semaphore ();
        mUpdateLock   = new Semaphore ();
    }


    //-------------------------------------------------------------------------
    /**
     * Decrease the readers counter by one to notify a reading process on the
     * object has been ended. Any waiting thread for write access will be
     * notified if no readers are present anymore.
     */
    public synchronized void endRead ()
        throws JahiaException
    {
        // Check if the object has not been deleted.
        isObjectAlive ();

        mReadCounter--;
        if (mReadCounter < 0) {
            mReadCounter = 0;
        }

        if ((mReadCounter == 0) && mWriteLock.isLocked ()) {
            // There is an writing action enabled, wake up the thread
            notify();
        }
    }


    //-------------------------------------------------------------------------
    /**
     * Get an exculsive update/modify/delete access on the internal object
     * data. This access will not prevent write access to the object, it prevents
     * another thread to enter the modify/update/delete process of an object.
     * This method doesn't wait until the an update access is available.
     *
     * @return  Return true if the update access could be received, or false,
     *          is no update access is allowed.
     */
    public final synchronized boolean getUpdateLock ()
        throws JahiaException
    {
        // Check if the object has not been deleted.
        isObjectAlive ();

        return mUpdateLock.tryLock();
    }


    //-------------------------------------------------------------------------
    /**
     * Get an exclusive write lock on the object's internal data. A call to
     * this method returns only when no other tread is reading intenal data
     * and will also prevent other threads to read the internal data.
     * Blocking an object to write/update/delete it's internal data, should be
     * done only during a short period of time. Remember, blocking the object
     * will block any other access to the object.
     */
    public synchronized void getWriteLock ()
        throws JahiaException
    {
        // Check if the object has not been deleted.
        isObjectAlive ();

        // Try to get the writing lock
        mWriteLock.lock();

        // once the lock is available, set the object in non-read state.
        mReadable = false;

        // if there are active readers, wait until there are no readers anymore.
        if (mReadCounter > 0) {
            try {
                wait();
            }
            catch (InterruptedException ex) {
            }
        }
    }


    //-------------------------------------------------------------------------
    /**
     * Increase the object's reader counter by one to notify the object a read
     * access has been started on the object. If the object is blocked, the
     * calling thread is inserted into the waiting list.
     */
    public synchronized void startRead ()
        throws JahiaException
    {
        // Check if the object has not been deleted.
        isObjectAlive ();

        if (mReadable) {
            mReadCounter++;
        } else {
            try {
                wait();
            }
            catch (InterruptedException ex) {
            }
        }
    }


    //-------------------------------------------------------------------------
    /** Release the update access lock.
     */
    public synchronized void releaseUpdateLock ()
        throws JahiaException
    {
        // Check if the object has not been deleted.
        isObjectAlive ();

        mUpdateLock.unlock();
    }


    //-------------------------------------------------------------------------
    /**
     * Release the exclusive write lock, and notify all the waiting threads
     * the object is available again.
     */
    public synchronized void releaseWriteLock ()
        throws JahiaException
    {
        // Check if the object has not been deleted.
        isObjectAlive ();

        mReadable = true;
        mWriteLock.unlock();
        notify();
    }

}
    // finish class JahiaObject