/*!
  @header EncoreExceptions
  @abstract Export of diverse exceptions
 
  @availability OS X, GNUstep
  @copyright 2004, 2005, 2006 Oliver Langer

  Author: Oliver Langer

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

  <pre>  
  -------------------------------------------------------------------------
  Modification history

  04.01.2005 ola     initial version
  22.08.2006 ola     license changed
  -------------------------------------------------------------------------
  </pre>
******************************************************************************/

#if !defined(__ECEXCEPTIONS_H)
#define __ECEXCEPTIONS_H

#include <Foundation/Foundation.h>

/*!
 * @class ECException
 * @abstract abstract base class of all exceptions
 */
@interface ECException : NSException {
  /**
   * This variable may refer to previously raised exceptions which caused
   * the raise of the current instance. Through this mechanism it is
   * possible to implement a stacktrace in future.
   */
  NSException *cause;
}

/*!
 * @method init
 * @abstract default constructor
 */
- init;
- (void) dealloc;


/*!
 * @method initWithReason
 * @abstract Initialization specifyin the reason
 */
- initWithReason: (NSString *) aReason;


/*!
 * @method cause
 * @abstract returns the exception which caused the raise of the receiver of 
 *   this message
 * @result the exception which caused the raise of the receiver of 
 *   this message or nil, if not given
 */
- (NSException *) cause;


/*!
 * @method raiseWithPredecessor
 * @abstract Raises the exception setting the hand-off exception as the cause
 *   of this raising.
 * @param predecessor Exception which caused the receiver of this message to be
 *   raised.
 */
- (void) raiseWithPredecessor: (NSException *) predecessor;


/*!
 * @method setCause
 * @abstract Specify the exception which has previously been thrown and will
 *   cause the receiver of this message to be raisen
 * @discussion Do only call this method once per instance! Otherwise it will
 *   throw an exception for itself!
 * @result
 * @throws ECIllegalArgumentException
 */
- setCause: (NSException *) causingException;

@end


/*!
 * @class ECIllegalArgumentException
 * @abstract Thrown in case of an illegal argument
 */
@interface ECIllegalArgumentException : ECException {

@private
  NSString *argumentInfo;
}


/*!
 * @method init
 * @param argumentInfo gives a hint about the argument
 */
- initWithArgumentInfo: (NSString *) anArgumentInfo;
- (void) dealloc;


/*!
 * @method argumentInfo
 * @result information about the result. May equal nil
 */
- (NSString *) argumentInfo;
@end


@interface ECPermissionDeniedException : ECException {
@private 
  NSString *accessObject;
}

/**
 * @method initForAccessObject
 * @abstract Initializer.
 * @param theAccessObject the object for which the permission could not be
 *   granted.
 * @discussion "obejct" is meant in an abstract manner here.
 */
- initForAccessObject: (NSString *) theAccessObject;
- (void) dealloc;


/**
 * @method accessObject
 * @result the object for which the access could not be granted
 * @discussion "obejct" is meant in an abstract manner here.
 */
- (NSString *) accessObject;

@end


/*!
 * @class ECIncompleteInitializationException
 * @abstract Thrown if an initialization is incomplete
 * @discussion 
 * Use the (derived) method initWithReason and "reason" to manage the reason.
 */
@interface ECIncompleteInitializationException : ECException
@end


/*! 
 * @class ECIllegalStateException
 * @abstract Thrown in case of an illegal state
 * @discussion manages a state info string
 */
@interface ECIllegalStateException : ECException {
  @private
    NSString *stateInfo;
	
	/**
	 * this reference may equal nil
	 */
	NSException *caughtException;
}

/*!
 * @method initWithIllegalStateInfo
 */
- initWithIllegalStateInfo: (NSString *) aStateInfo;
- initWithIllegalStateInfo: (NSString *) aStateInfo 
  caughtException: (NSException *) anException;
- (void) dealloc;


/*!
 * @method caughtException
 * @result return the exception this illegale state is based on.
 *  The result may equal nil in case the exception has not been given
 */
- (NSException *) caughtException;


/*! 
 * @method stateInfo
 * @result information about the illegal state
 */
- (NSString *) stateInfo;
@end  
  
  
/*!
 * @class ECAlreadyExistsException
 * @abstract Thrown if a resource already exists
 */
@interface ECAlreadyExistsException : ECException {
  @private
    NSString *resourceInformation;
}


/*!
 * @method initWithResourceInformation
 * @abstract Initializes the instance with the appropriate information about
 *   the resource
 * @param aResourceInfo information about the resource
 * @result self
 */
- initWithResourceInformation: (NSString *) aResourceInfo;
- (void) dealloc;


/*!
 * @method resourceInformation
 * @result information about the resource
 */
- (NSString *) resourceInformation;
@end


/*!
 * @class ECIllegalOperationException
 * @abstract Thrown if the operation being called is not defined for
 *  the current state/context.
 */
@interface ECIllegalOperationException : ECException {
  @private
    NSString *operationInformation;
}

/*!
 * @method initWithOperationInformation
 * @param operationInfo Information about the operation
 * @result self
 */
- initWithOperationInformation: (NSString *) operationInfo;
- (void) dealloc;


/*!
 * @method operationInformation
 * @result Information about the operation
 */
- (NSString *) operationInformation;
@end


/*! 
 * @class ECNotImplementedException
 * @abstract Thrown if a functionality is referred which has not been
 *   implemented yet.
 */
@interface ECNotImplementedException : ECException {
  @private 
    NSString *operationInformation;
}

/*!
 * @method initWithOperationInformation
 * @param anInfo information about the unimplemented feature
 * @result self
 */
- initWithOperationInformation: (NSString *) anInfo;
- (void) dealloc;

/*!
 * @method operationInformation
 * @result Returns information about the unimplemented feature
 */
- (NSString *) operationInformation;
@end


/*!
 * @class ECAssertionException
 * @abstract Thrown if an assertion does not equal TRUE after evaluation
 */
@interface ECAssertionException : ECException {
  @private
    NSString *assertionInfo;
}

/*!
 * @method initWithAssertionInfo
 * @param theInfo Information regarding the assertion failure. May contain
 *   context info etc.
 * @result self
 */
- initWithAssertionInfo: (NSString *) theInfo;
- (void) dealloc;


/*!
 * @method assertionInfo
 * @result information about the assertion failure
 */
- (NSString *) assertionInfo;
@end

#endif