=== Summary ===

=== Summary ===

Using [[checked exception]] to track essential attributes that yet need to be provided is a nice and no-overhead way to co-relate the requested runtime behavior with compiler and let users know at compile time that their code is wrong and needs additional tweaks. Evolution of this pattern works nicely with respect to [[binary compatibility]] in [[Java]] thanks to [[erasure]] of generic types.

Using [[checked exception]] to track essential attributes and to whine when they aren't set is a nice and no-overhead way to co-relate the requested runtime behavior with compiler and let users know at compile time that their code is wrong and needs additional tweaks. Evolution of this pattern works nicely with respect to [[binary compatibility]] in [[Java]] thanks to [[erasure]] of generic types.

=== [[Evolution]] ===

=== [[Evolution]] ===

An interesting question from an [[evolution]] point of view: what happens when we need to add new essential attribute? Obviously, if we want 100% [[BackwardCompatibility]] then we should add new [[builder]] class:

An interesting question from an [[evolution]] point of view: what happens when we need to add a new essential attribute? Obviously, if we want 100% [[BackwardCompatibility]] then we should add new [[builder]] class:

<source lang="java">

<source lang="java">

=== Drawbacks ===

=== Drawbacks ===

The biggest strength of this pattern - e.g. '''N''' independent conditions is also the biggest flaw: Imagine [[clueless]] users seeing the signature with n-[[exception]] type parameters! They would be scared. On the other hand, the typical usage of the [[builder]] pattern doesn't expose the type variables at all:

The biggest strength of this pattern - e.g. '''N''' independent conditions is also its biggest flaw: Imagine [[clueless]] users seeing the signature with n-[[exception]] type parameters! They would be scared. On the other hand, the typical usage of the [[builder]] pattern doesn't expose the type variables at all:

<source lang="java">

<source lang="java">

=== Drawbacks ===

=== Drawbacks ===

The biggest strength of this pattern - e.g. '''N''' independent condition is also the biggest flaw: Imagine [[clueless]] users seeing the signature with n-[[exception]] type parameters! They would be scared. On the other hand, the typical usage of the [[builder]] pattern doesn't expose the type variables at all:

The biggest strength of this pattern - e.g. '''N''' independent conditions is also the biggest flaw: Imagine [[clueless]] users seeing the signature with n-[[exception]] type parameters! They would be scared. On the other hand, the typical usage of the [[builder]] pattern doesn't expose the type variables at all:

<source lang="java">

<source lang="java">

</source>

</source>

Each of the '''E'''-th type parameter is representing independent single condition: Was the associated attribute set or not? All of the conditions need to be satisfied otherwise the '''build()''' method keeps throwing a [[checked exception]]. This kind of ''or-behavior'' is impossible to achieve with a single return type in [[Java]] type system.

Each of the '''E'''-th type parameter is representing independent single condition and can be used for whining: Was the associated attribute set or not? All of the conditions need to be satisfied otherwise the '''build()''' method keeps whining - e.g. throwing a [[checked exception]]. This kind of ''or-behavior'' is impossible to achieve with a single return type in [[Java]] type system.

=== Drawbacks ===

=== Drawbacks ===

=== Why Does It Work? ===

=== Why Does It Work? ===

The [[ChameleonBuilder]] works only with a single essential attribute because each attribute can influence only a single generic type. The reason why this new pattern works is that one method can have unlimited number of {{JDK|java/lang|Exception}}s in its '''throws''' clause. Depending on the number of essential attributes one defines '''N''' type parameters:

The [[ChameleonBuilder]] works only with a single essential attribute because each attribute can influence only a single generic type. The reason why the [[WhiningBuilder]] pattern works is that one method can have unlimited number of {{JDK|java/lang|Exception}}s in its '''throws''' clause. Depending on the number of essential attributes one defines '''N''' type parameters:

<source lang="java">

<source lang="java">

one gets a compilation error, as the [[builder]] ''whines''! Its '''build''' method throws a [[checked exception]]. Even if one specifies '''name''', the error still remains. Only if both '''name''' and '''mimeType''' are specified the [[checked exception]]s go away (as they are replaced by runtime [[exception]]s) and the compilation succeeds.

one gets a compilation error, as the [[builder]] ''whines''! Its '''build''' method throws a [[checked exception]]. Even if one specifies '''name''', the error still remains. Only if both '''name''' and '''mimeType''' are specified the [[checked exception]]s go away (as they are replaced by runtime [[exception]]s) and the compilation succeeds.

The runtime and compile time aspects work in orchestration: if a [[checked exception]] is reported - it will also be thrown. E.g. trying to put a '''try'''/'''catch''' block around the the '''build()''' call makes no sense. If the [[exception]] is declared, it will really be generated.

The runtime and compile time aspects work in orchestration: if a [[checked exception]] is reported - it will also be thrown. E.g. trying to put a '''try'''/'''catch''' block around the '''build()''' call makes no sense. If the [[exception]] is declared, it will really be generated.

=== Explaining Why ===

=== Explaining Why ===

</source>

</source>

one gets a compilation error, as the build method throws a [[checked exception]]. Even if one specifies '''name''', the error still remains. Only if both '''name''' and '''mimeType''' are specified the [[checked exception]]s go away (as they are replaced by runtime [[exception]]s) and the compilation succeeds.

one gets a compilation error, as the [[builder]] ''whines''! Its '''build''' method throws a [[checked exception]]. Even if one specifies '''name''', the error still remains. Only if both '''name''' and '''mimeType''' are specified the [[checked exception]]s go away (as they are replaced by runtime [[exception]]s) and the compilation succeeds.

The runtime and compile time aspects work in orchestration: if a [[checked exception]] is reported - it will also be thrown. E.g. trying to put a '''try'''/'''catch''' block around the the '''build()''' call makes no sense. If the [[exception]] is declared, it will really be generated.

The runtime and compile time aspects work in orchestration: if a [[checked exception]] is reported - it will also be thrown. E.g. trying to put a '''try'''/'''catch''' block around the the '''build()''' call makes no sense. If the [[exception]] is declared, it will really be generated.

</source>

</source>

one gets a compilation error, as the build method throws a [[checked exception]]. Even if one specifies '''name''', the error still remains. Only if both '''name''' and '''mimeType''' are specified the [[checked exception]]s go away (as they are replaced by runtime [[exception]]s).

one gets a compilation error, as the build method throws a [[checked exception]]. Even if one specifies '''name''', the error still remains. Only if both '''name''' and '''mimeType''' are specified the [[checked exception]]s go away (as they are replaced by runtime [[exception]]s) and the compilation succeeds.

The runtime and compile time aspects work in orchestration: if a [[checked exception]] is reported - it will also be thrown. E.g. trying to put a '''try'''/'''catch''' block around the the '''build()''' call makes no sense. If the [[exception]] is declared, it will really be generated.

The runtime and compile time aspects work in orchestration: if a [[checked exception]] is reported - it will also be thrown. E.g. trying to put a '''try'''/'''catch''' block around the the '''build()''' call makes no sense. If the [[exception]] is declared, it will really be generated.