com.buildforge.services.common.api
Class APIException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by com.buildforge.services.common.ServiceException
              extended by com.buildforge.services.common.api.APIException
All Implemented Interfaces:
java.io.Serializable

public class APIException
extends ServiceException

Internationalized exceptions for the API layer.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class com.buildforge.services.common.ServiceException
ServiceException.WrappedServiceException
 
Field Summary
 
Fields inherited from class com.buildforge.services.common.ServiceException
CLASS
 
Constructor Summary
APIException(MessageDBO msg)
          Construct a new APIException from a pre-built message.
APIException(MessageDBO msg, java.lang.Throwable cause)
          Construct a new APIException from a pre-built message.
APIException(java.lang.String id)
          Construct a new APIException.
APIException(java.lang.String id, int arg)
          Construct a new APIException.
APIException(java.lang.String id, int arg0, int arg1)
          Construct a new APIException.
APIException(java.lang.String id, int arg0, java.lang.String arg1)
          Construct a new APIException.
APIException(java.lang.String id, int arg, java.lang.Throwable cause)
          Construct a new APIException.
APIException(java.lang.String id, java.lang.String arg)
          Construct a new APIException.
APIException(java.lang.String id, java.lang.String[] args)
          Construct a new APIException.
APIException(java.lang.String id, java.lang.String[] args, java.lang.Throwable cause)
          Construct a new APIException
APIException(java.lang.String id, java.lang.String arg0, int arg1)
          Construct a new APIException.
APIException(java.lang.String id, java.lang.String arg0, java.lang.String arg1)
          Construct a new APIException.
APIException(java.lang.String id, java.lang.String arg, java.lang.Throwable cause)
          Construct a new APIException.
APIException(java.lang.String id, java.lang.Throwable cause)
          Construct a new APIException.
 
Method Summary
static APIException badEnum(java.lang.Class<? extends java.lang.Enum<?>> cls, java.lang.String value)
          Convenience method for creating an APIException that reports an attempt to use an invalid value for an enumerated constant.
static APIException badIndex(int index)
          Index out of bounds.
static APIException collision(java.lang.String dbo, java.lang.String field, int value)
          Convenience method for collisions on numeric fields.
static APIException collision(java.lang.String dbo, java.lang.String field, java.lang.String value)
          Returns a new exception indicating that a create or rename failed because there was some form of data collision.
static APIException dead(java.lang.String dbo)
          Convenience method for creating an APIException that reports the attempt to manipulate an object that the client has not yet determined to be live.
static APIException invalid(java.lang.String dbo, java.lang.String field)
          Convenience method for creating an APIException that reports the attempt to make a request that omits or gives an invalid value for a specific, required field.
static APIException live(java.lang.String dbo)
          Convenience method for creating an APIException that reports the attempt to create an object that is already known to the client to be a live object.
static APIException malformed(java.lang.String dbo, int expected, int got)
          Convenience method for creating an APIException that reports the receipt of a malformed DBO from the wire protocol.
static APIException missing(java.lang.String key)
          Missing required parameter.
static APIException needLevel(int level)
          Access denied.
static APIException needPerm(Permission perm)
          Permission denied.
static APIException needRoot()
          Permission denied.
static APIException needSystem()
          Permission denied.
static APIException noRows(java.lang.String dbo, java.lang.String id)
          Convenience method for creating an APIException that reports the attempt to update an object for which no matching rows could be found in the database.
 
Methods inherited from class com.buildforge.services.common.ServiceException
getMessage, getMessageKey, getMessageObject, wrap
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

APIException

public APIException(MessageDBO msg)
Construct a new APIException from a pre-built message. The cause will not be initialized.

Parameters:
msg - the internationalized error message
Throws:
java.lang.NullPointerException - if msg is null

APIException

public APIException(MessageDBO msg,
                    java.lang.Throwable cause)
Construct a new APIException from a pre-built message.

Parameters:
msg - the internationalized error message
cause - an exception that caused this exception to occur
Throws:
java.lang.NullPointerException - if msg is null

APIException

public APIException(java.lang.String id)
Construct a new APIException. The message must not require any arguments, and the cause will be left uninitialized.

Parameters:
id - a unique error id for a translatable message

APIException

public APIException(java.lang.String id,
                    java.lang.String[] args)
Construct a new APIException. The cause will not be initialized.

Parameters:
id - a unique error id for a translatable message
args - arguments for the translation

APIException

public APIException(java.lang.String id,
                    java.lang.String arg0,
                    int arg1)
Construct a new APIException. The cause will not be initialized. This is a convenience method for the fairly common case where the exception message takes a string and an integer as its arguments.


APIException

public APIException(java.lang.String id,
                    int arg0,
                    java.lang.String arg1)
Construct a new APIException. The cause will not be initialized. This is a convenience method for the fairly common case where the exception message takes an integer and a string as its arguments.


APIException

public APIException(java.lang.String id,
                    java.lang.String arg0,
                    java.lang.String arg1)
Construct a new APIException. The cause will not be initialized. This is a convenience method for the fairly common case where the exception message takes two strings as its arguments.

Parameters:
id - a unique error id for a translatable message
arg - a single argument for the translation

APIException

public APIException(java.lang.String id,
                    int arg0,
                    int arg1)
Construct a new APIException. The cause will not be initialized. This is a convenience method for the fairly common case where the exception message takes two integers as its arguments.

Parameters:
id - a unique error id for a translatable message
arg - a single argument for the translation

APIException

public APIException(java.lang.String id,
                    int arg)
Construct a new APIException. The cause will not be initialized. This is a convenience method for the fairly common case where the exception message takes a single integer as its argument.

Parameters:
id - a unique error id for a translatable message
arg - a single argument for the translation

APIException

public APIException(java.lang.String id,
                    java.lang.String arg)
Construct a new APIException. The cause will not be initialized. This is a convenience method for the fairly common case where the exception message takes a single String as its argument.

Parameters:
id - a unique error id for a translatable message
arg - a single argument for the translation

APIException

public APIException(java.lang.String id,
                    java.lang.Throwable cause)
Construct a new APIException. The message must not require any arguments.

Parameters:
id - a unique error id for a translatable message
cause - the exception to use when initializing the cause

APIException

public APIException(java.lang.String id,
                    java.lang.String[] args,
                    java.lang.Throwable cause)
Construct a new APIException

Parameters:
id - a unique error id for a translatable message
args - arguments for the translation
cause - the exception to use when initializing the cause

APIException

public APIException(java.lang.String id,
                    int arg,
                    java.lang.Throwable cause)
Construct a new APIException. This is a convenience method for the fairly common case where the exception message takes a single integer as its argument.

Parameters:
id - a unique error id for a translatable message
arg - a single argument for the translation
cause - the exception to use when initializing the cause

APIException

public APIException(java.lang.String id,
                    java.lang.String arg,
                    java.lang.Throwable cause)
Construct a new APIException. This is a convenience method for the fairly common case where the exception message takes a single String as its argument.

Parameters:
id - a unique error id for a translatable message
arg - a single argument for the translation
cause - the exception to use when initializing the cause
Method Detail

badEnum

public static APIException badEnum(java.lang.Class<? extends java.lang.Enum<?>> cls,
                                   java.lang.String value)
Convenience method for creating an APIException that reports an attempt to use an invalid value for an enumerated constant.

Parameters:
cls - the enumeration class
value - the value that was used (may be null)
Returns:
the new exception

invalid

public static APIException invalid(java.lang.String dbo,
                                   java.lang.String field)
Convenience method for creating an APIException that reports the attempt to make a request that omits or gives an invalid value for a specific, required field. Example:

If en_US.ini contains:

 Cron=Schedule Entry
 ID=Identifier
 GenericInvalid=A valid %s %s must be specified.
 
then the exception generated by calling invalid("Cron", "ID") will render its message as "A valid Schedule Entry Identifier must be specified." in the en_US locale.

Parameters:
dbo - the type of object that was not valid (indirect)
field - the type of identifying object field that was invalid (indirect)
Returns:
the new exception

malformed

public static APIException malformed(java.lang.String dbo,
                                     int expected,
                                     int got)
Convenience method for creating an APIException that reports the receipt of a malformed DBO from the wire protocol. This is used when the DBO does not have the correct number of data fields.

Parameters:
dbo - the type of database object causing the problem (indirect)
expected - the number of data fields that were expected
got - the number of data fields that were actually received
Returns:
the new exception

dead

public static APIException dead(java.lang.String dbo)
Convenience method for creating an APIException that reports the attempt to manipulate an object that the client has not yet determined to be live.

Parameters:
dbo - the type of database object causing the problem (indirect)
Returns:
the new exception

live

public static APIException live(java.lang.String dbo)
Convenience method for creating an APIException that reports the attempt to create an object that is already known to the client to be a live object.

Parameters:
dbo - the type of database object causing the problem (indirect)
Returns:
the new exception

noRows

public static APIException noRows(java.lang.String dbo,
                                  java.lang.String id)
Convenience method for creating an APIException that reports the attempt to update an object for which no matching rows could be found in the database. This generally means that the object was deleted before the request, or that the object is referenced by name and the name has been changed.

Parameters:
dbo - the type of database object causing the problem (indirect)
id - the identifier used for the lookup
Returns:
the new exception

collision

public static APIException collision(java.lang.String dbo,
                                     java.lang.String field,
                                     java.lang.String value)
Returns a new exception indicating that a create or rename failed because there was some form of data collision. In general this means that the object's name or id was already in use, but this can also apply to other unique fields, such as the user's login name.

Parameters:
dbo - the type of database object causing the problem (indirect)
field - the type of identifying object field that was invalid (indirect)
value - the value that is already in use
Returns:
the new exception

collision

public static APIException collision(java.lang.String dbo,
                                     java.lang.String field,
                                     int value)
Convenience method for collisions on numeric fields. This is equivilant to calling exists( dbo, field, String.valueOf(value) ).

Parameters:
dbo - the type of database object causing the problem (indirect)
field - the type of identifying object field that was invalid (indirect)
value - the value that is already in use
Returns:
the new exception

missing

public static APIException missing(java.lang.String key)
Missing required parameter.


needRoot

public static APIException needRoot()
Permission denied. This version of the call is used when Root access is needed and the auth context does not have Root access rights.


needSystem

public static APIException needSystem()
Permission denied. This version of the call is used when SYSTEM access is needed and the auth context does not have SYSTEM access rights.


needPerm

public static APIException needPerm(Permission perm)
Permission denied. This version of the call is used for a failed permission check.


needLevel

public static APIException needLevel(int level)
Access denied. This version of the call is used when a request attempts to set a level to which the user does not have access. Attempts to access an object that already has such a level set should generally pretend that the object doesn't even exist, instead.


badIndex

public static APIException badIndex(int index)
Index out of bounds.