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    
015    package 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     */
021    public 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    }