001/*
002 * file StpReleasable.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 *
007 * com.ibm.rational.wvcm.stp.StpReleasable
008 *
009 * (C) Copyright IBM Corporation 2004, 2008.  All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012 */
013
014
015package com.ibm.rational.wvcm.stp;
016
017/**
018 * A interface for objects that hold resources that can (and in some
019 * cases really should) be released prior to garbage collection.
020 */
021public interface StpReleasable {
022
023    /**
024     * A distinguished unchecked exception for use by implementations
025     * of Releasable.
026     * 
027     * Implementations of Releasable should document if they actually
028     * throw this exception, under what conditions it occurs and what
029     * to expect for the exception's "cause" (Throwable.getCause()).
030     * 
031     * <p>See {@link java.lang.Throwable} for a description of this general
032     * idiom of documenting/returning unchecked exceptions from
033     * general interfaces.
034     */    
035    public static class ReleaseException extends RuntimeException
036    {
037        /**
038         * 
039         */
040        private static final long serialVersionUID = -6014447477020398274L;
041
042        public ReleaseException(Throwable ex) {
043            super(ex);
044        }
045    }
046    
047    /**
048     * Release the resources held by this object.
049     * 
050     * Class's Javadoc comments indicate whether or not the unchecked
051     * ReleaseException can be thrown.
052     */
053    void release();
054}