pl.wavesoftware.eid.utils

Class EidPreconditions

java.lang.Object

pl.wavesoftware.eid.utils.EidPreconditions

public final class EidPreconditions
extends Object

This class shouldn't be used in any public API or library. It is designed to be used for in-house development of end user applications which will report Bugs in standardized error pages or post them to issue tracker.

Static convenience methods that help a method or constructor check whether it was invoked correctly (whether its preconditions have been met). These methods generally accept a boolean expression which is expected to be true (or in the case of checkNotNull, an object reference which is expected to be non-null). When false (or null) is passed instead, the EidPreconditions method throws an unchecked exception, which helps the calling method communicate to its caller that that caller has made a mistake.

Each method accepts a EID String or Eid object, which is designed to ease of use and provide strict ID for given Exception usage. This approach speed up development of large application and helps support teams to by giving the both static and random ID for each possible unpredicted bug.

This is best to use with tools and plugins like EidGenerator for Netbeans IDE

Example:

   /**
    * Returns the positive square root of the given value.
    *
    * @throws EidIllegalArgumentException if the value is negative
    */
   public static double sqrt(double value) {
     EidPreconditions.checkArgument(value >= 0.0, "20150718:012333");
     // calculate the square root
   }

   void exampleBadCaller() {
     double d = sqrt(-1.0);
   }
 

In this example, checkArgument throws an EidIllegalArgumentException to indicate that exampleBadCaller made an error in its call to sqrt. Exception, when it will be printed will contain user given Eid and also Randomly generated ID. Those fields can be displayed to user on error page on posted directly to issue tracker.

Example:

 // Main application class for ex.: http servlet
    try {
        performRequest(request, response);
    } catch (EidRuntimeException ex) {
        issuesTracker.put(ex);
        throw ex;
    }
 

Functional try to execute blocks

Using functional blocks to handle operations, that are intended to operate properly, simplify the code and makes it more readable. It's also good way to deal with untested, uncovered catch blocks. It's easy and gives developers nice way of dealing with countless operations that suppose to work as intended.

Example:

     InputStream is = EidPreconditions.tryToExecute(new UnsafeSupplier<InputStream>() {
        @Override
         public InputStream get() throws IOException {
             return this.getClass().getClassLoader()
                 .getResourceAsStream("project.properties");
         }
     }, "20150718:121521");
 

Since:

0.1.0 (idea imported from Guava Library and COI code)

Author:

Krzysztof Suszyński

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	EidPreconditions.RiskyCode<R> Deprecated. Use instead EidPreconditions.UnsafeSupplier or EidPreconditions.UnsafeProcedure. To be removed in next release.
static interface	EidPreconditions.UnsafeProcedure This unsafe procedure can be used to execute a code block that can throw some checked Exceptions, that you would like not to process, because they are unrecoverable bugs.
static interface	EidPreconditions.UnsafeSupplier<T> This unsafe supplier can be used to execute a code block that needs to return some value and can throw some checked Exceptions, that you would like not to process, because they are unrecoverable bugs.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EidPreconditions()

Method Summary

Methods

Modifier and Type	Method and Description
static void	checkArgument(Boolean expression, Eid eid) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(Boolean expression, Eid eid, String messageFormat, Object... parameters) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(Boolean expression, String eid) Ensures the truth of an expression involving one or more parameters to the calling method.
static void	checkArgument(Boolean expression, String eid, String messageFormat, Object... parameters) Ensures the truth of an expression involving one or more parameters to the calling method.
static int	checkElementIndex(int index, int size, Eid eid) Ensures that index specifies a valid element in an array, list or string of size size.
static int	checkElementIndex(int index, int size, Eid eid, String messageFormat, Object... parameters) Ensures that index specifies a valid element in an array, list or string of size size.
static int	checkElementIndex(int index, int size, String eid) Ensures that index specifies a valid element in an array, list or string of size size.
static int	checkElementIndex(int index, int size, String eid, String messageFormat, Object... parameters) Ensures that index specifies a valid element in an array, list or string of size size.
static <T> T	checkNotNull(T reference, Eid eid) Ensures that an object reference passed as a parameter to the calling method is not null.
static <T> T	checkNotNull(T reference, Eid eid, String messageFormat, Object... parameters) Ensures that an object reference passed as a parameter to the calling method is not null.
static <T> T	checkNotNull(T reference, String eid) Ensures that an object reference passed as a parameter to the calling method is not null.
static <T> T	checkNotNull(T reference, String eid, String messageFormat, Object... parameters) Ensures that an object reference passed as a parameter to the calling method is not null.
static void	checkState(Boolean expression, Eid eid) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkState(Boolean expression, Eid eid, String messageFormat, Object... parameters) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkState(Boolean expression, String eid) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static void	checkState(Boolean expression, String eid, String messageFormat, Object... parameters) Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.
static <R> R	tryToExecute(EidPreconditions.RiskyCode<R> code, Eid eid) Deprecated. Use instead tryToExecute(UnsafeSupplier, Eid). To be removed in next release.
static <R> R	tryToExecute(EidPreconditions.RiskyCode<R> code, String eid) Deprecated. Use instead tryToExecute(UnsafeSupplier, String). To be removed in next release.
static void	tryToExecute(EidPreconditions.UnsafeProcedure procedure, Eid eid) Tries to execute code in given unsafe procedure code block, and if exception is thrown, it will gets rethrown as a EidRuntimeException with eid given as a argument.
static void	tryToExecute(EidPreconditions.UnsafeProcedure procedure, String eid) For more info in JavaDoc see tryToExecute(UnsafeProcedure, Eid)
static <R> R	tryToExecute(EidPreconditions.UnsafeSupplier<R> supplier, Eid eid) Tries to execute code in given unsafe supplier code block, and if exception is thrown, it will gets rethrown as a EidRuntimeException with eid given as a argument.
static <R> R	tryToExecute(EidPreconditions.UnsafeSupplier<R> supplier, String eid) For more info in JavaDoc see tryToExecute(UnsafeSupplier, Eid)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EidPreconditions

protected EidPreconditions()

Method Detail

checkArgument

public static void checkArgument(@Nullable
                 Boolean expression,
                 @Nonnull
                 String eid)

Ensures the truth of an expression involving one or more parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception ID to use if the check fails; will be converted to Eid

Throws:

EidIllegalArgumentException - if expression is false

EidNullPointerException - if expression is null

checkArgument

public static void checkArgument(@Nullable
                 Boolean expression,
                 @Nonnull
                 String eid,
                 @Nonnull
                 String messageFormat,
                 Object... parameters)

Ensures the truth of an expression involving one or more parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception ID to use if the check fails; will be converted to Eid

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Throws:

EidIllegalArgumentException - if expression is false

EidNullPointerException - if expression or eid are null

checkArgument

public static void checkArgument(@Nullable
                 Boolean expression,
                 @Nonnull
                 Eid eid)

Ensures the truth of an expression involving one or more parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception ID to use if the check fails; will be converted to Eid

Throws:

EidIllegalArgumentException - if expression is false

EidNullPointerException - if expression is null

checkArgument

public static void checkArgument(@Nullable
                 Boolean expression,
                 @Nonnull
                 Eid eid,
                 @Nonnull
                 String messageFormat,
                 Object... parameters)

Ensures the truth of an expression involving one or more parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception ID to use if the check fails; will be converted to Eid

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Throws:

EidIllegalArgumentException - if expression is false

EidNullPointerException - if expression is null

checkState

public static void checkState(@Nullable
              Boolean expression,
              @Nonnull
              String eid)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

Throws:

EidIllegalStateException - if expression is false

EidNullPointerException - if expression is null

checkState

public static void checkState(@Nullable
              Boolean expression,
              @Nonnull
              String eid,
              @Nonnull
              String messageFormat,
              Object... parameters)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Throws:

EidIllegalStateException - if expression is false

EidNullPointerException - if expression is null

checkState

public static void checkState(@Nullable
              Boolean expression,
              @Nonnull
              Eid eid)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

Throws:

EidIllegalStateException - if expression is false

checkState

public static void checkState(@Nullable
              Boolean expression,
              @Nonnull
              Eid eid,
              @Nonnull
              String messageFormat,
              Object... parameters)

Ensures the truth of an expression involving the state of the calling instance, but not involving any parameters to the calling method.

Parameters:

expression - (Nullable) a boolean expression

eid - (Nonnull) the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Throws:

EidIllegalStateException - if expression is false

checkNotNull

@Nonnull
public static <T> T checkNotNull(@Nullable
                         T reference,
                         @Nonnull
                         String eid)

Ensures that an object reference passed as a parameter to the calling method is not null.

Type Parameters:

T - type of object reference being checked

Parameters:

reference - an object reference

eid - the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

Returns:

the non-null reference that was validated

Throws:

EidNullPointerException - if reference is null

checkNotNull

@Nonnull
public static <T> T checkNotNull(@Nullable
                         T reference,
                         @Nonnull
                         String eid,
                         @Nonnull
                         String messageFormat,
                         Object... parameters)

Ensures that an object reference passed as a parameter to the calling method is not null.

Type Parameters:

T - type of object reference being checked

Parameters:

reference - an object reference

eid - the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Returns:

the non-null reference that was validated

Throws:

EidNullPointerException - if reference is null

checkNotNull

@Nonnull
public static <T> T checkNotNull(@Nullable
                         T reference,
                         @Nonnull
                         Eid eid)

Ensures that an object reference passed as a parameter to the calling method is not null.

Type Parameters:

T - type of object reference being checked

Parameters:

reference - an object reference

eid - the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

Returns:

the non-null reference that was validated

Throws:

EidNullPointerException - if reference is null

checkNotNull

@Nonnull
public static <T> T checkNotNull(@Nullable
                         T reference,
                         @Nonnull
                         Eid eid,
                         @Nonnull
                         String messageFormat,
                         Object... parameters)

Ensures that an object reference passed as a parameter to the calling method is not null.

Type Parameters:

T - type of object reference being checked

Parameters:

reference - an object reference

eid - the exception message to use if the check fails; will be converted to a string using String.valueOf(Object)

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Returns:

the non-null reference that was validated

Throws:

EidNullPointerException - if reference is null

checkElementIndex

public static int checkElementIndex(int index,
                    int size,
                    @Nonnull
                    String eid)

Ensures that index specifies a valid element in an array, list or string of size size. An element index may range from zero, inclusive, to size, exclusive.

Parameters:

index - a user-supplied index identifying an element of an array, list or string

size - the size of that array, list or string

eid - the text to use to describe this index in an error message

Returns:

the value of index

Throws:

EidIndexOutOfBoundsException - if index is negative or is not less than size

EidIllegalArgumentException - if size is negative

checkElementIndex

public static int checkElementIndex(int index,
                    int size,
                    @Nonnull
                    String eid,
                    @Nonnull
                    String messageFormat,
                    Object... parameters)

Ensures that index specifies a valid element in an array, list or string of size size. An element index may range from zero, inclusive, to size, exclusive.

Parameters:

index - a user-supplied index identifying an element of an array, list or string

size - the size of that array, list or string

eid - the text to use to describe this index in an error message

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Returns:

the value of index

Throws:

EidIndexOutOfBoundsException - if index is negative or is not less than size

EidIllegalArgumentException - if size is negative

checkElementIndex

public static int checkElementIndex(int index,
                    int size,
                    @Nonnull
                    Eid eid)

Ensures that index specifies a valid element in an array, list or string of size size. An element index may range from zero, inclusive, to size, exclusive.

Parameters:

index - a user-supplied index identifying an element of an array, list or string

size - the size of that array, list or string

eid - the text to use to describe this index in an error message

Returns:

the value of index

Throws:

EidIndexOutOfBoundsException - if index is negative or is not less than size

EidIllegalArgumentException - if size is negative

checkElementIndex

public static int checkElementIndex(int index,
                    int size,
                    @Nonnull
                    Eid eid,
                    @Nonnull
                    String messageFormat,
                    Object... parameters)

Ensures that index specifies a valid element in an array, list or string of size size. An element index may range from zero, inclusive, to size, exclusive.

Parameters:

index - a user-supplied index identifying an element of an array, list or string

size - the size of that array, list or string

eid - the text to use to describe this index in an error message

messageFormat - message format in form of String.format(String, Object...)

parameters - parameters fo message format in for of String.format(String, Object...)

Returns:

the value of index

Throws:

EidIndexOutOfBoundsException - if index is negative or is not less than size

EidIllegalArgumentException - if size is negative

tryToExecute

@Nullable
@Deprecated
public static <R> R tryToExecute(@Nonnull
                                     EidPreconditions.RiskyCode<R> code,
                                     @Nonnull
                                     String eid)

Deprecated. Use instead tryToExecute(UnsafeSupplier, String). To be removed in next release.

tryToExecute

@Deprecated
@Nullable
public static <R> R tryToExecute(@Nonnull
                                     EidPreconditions.RiskyCode<R> code,
                                     @Nonnull
                                     Eid eid)

Deprecated. Use instead tryToExecute(UnsafeSupplier, Eid). To be removed in next release.

tryToExecute

@Nullable
public static <R> R tryToExecute(@Nonnull
                          EidPreconditions.UnsafeSupplier<R> supplier,
                          @Nonnull
                          String eid)

For more info in JavaDoc see tryToExecute(UnsafeSupplier, Eid)

Type Parameters:

R - return type

Parameters:

supplier - unsafe supplier code to be executed within a try-catch block

eid - unique developer identifier from date for ex.: "20150716:123200"

Returns:

A block of code return type, if exception is not thrown

Throws:

EidRuntimeException - if code block thrown any exception, which in that case is wrapped in EidRuntimeException

See Also:

tryToExecute(UnsafeSupplier, Eid)

tryToExecute

public static void tryToExecute(@Nonnull
                EidPreconditions.UnsafeProcedure procedure,
                @Nonnull
                String eid)

For more info in JavaDoc see tryToExecute(UnsafeProcedure, Eid)

Parameters:

procedure - unsafe procedure code to be executed within a try-catch block

eid - unique developer identifier from date for ex.: "20150716:123200"

Throws:

EidRuntimeException - if code block thrown any exception, which in that case is wrapped in EidRuntimeException

See Also:

tryToExecute(UnsafeProcedure, Eid)

tryToExecute

@Nullable
public static <R> R tryToExecute(@Nonnull
                          EidPreconditions.UnsafeSupplier<R> supplier,
                          @Nonnull
                          Eid eid)

Tries to execute code in given unsafe supplier code block, and if exception is thrown, it will gets rethrown as a EidRuntimeException with eid given as a argument. This is because this exception is threaded as a software bug!

Example:

 Document doc = EidPreconditions.tryToExecute(new UnsafeSupplier<Document>() {
    @Override
     public Document get() throws SAXException, IOException {
          DocumentBuilder docBuilder = ...
          return docBuilder.parse(new InputSource(reader));
     }
 }, new Eid("20150718:121521"));
 

Type Parameters:

R - return type

Parameters:

supplier - unsafe supplier code to be executed within a try-catch block

eid - unique developer identifier from date for ex.: "20150716:123200"

Returns:

A block of code return type, if exception is not thrown

Throws:

EidRuntimeException - if code block thrown any exception, which in that case is wrapped in EidRuntimeException

tryToExecute

public static void tryToExecute(@Nonnull
                EidPreconditions.UnsafeProcedure procedure,
                @Nonnull
                Eid eid)

Tries to execute code in given unsafe procedure code block, and if exception is thrown, it will gets rethrown as a EidRuntimeException with eid given as a argument. This is because this exception is threaded as a software bug!

Example:

 EidPreconditions.tryToExecute(new UnsafeProcedure() {
    @Override
     public void execute() throws EJBException {
          em.persist(user);
     }
 }, new Eid("20151117:184627"));
 

Parameters:

procedure - unsafe procedure code to be executed within a try-catch block

eid - unique developer identifier from date for ex.: "20150716:123200"

Throws:

EidRuntimeException - if code block thrown any exception, which in that case is wrapped in EidRuntimeException