The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity|clear]] ones. Yet the result is still not ideal. Something is missing.

The [[fuzziness]] is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity|clear]] ones. Yet the result is still not ideal. Something is missing.

This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

<source lang="java" snippet="sidemeanings.Mixed.Clean.Factory"/>

<source lang="java" snippet="sidemeanings.Mixed.Clean.Factory"/>

The originally '''protected abstract''' methods are moved to ''Provider'' interface. Interface methods are '''public''' and this might seem like a contradiction to [[ClarityOfAccessModifiers]]. However, it is not. The instances of ''Provider'' interface are not accessible to [[ClientAPI|clients]] of the [[API]]. They are hidden and only useful for the ''create'' factory method that turns them into ''NonMixed'' instances. As such they are ''single meaning'' methods with only one message: ''implement me, don't call me!''. Their [[clarity]] is kept.

The originally '''protected abstract''' methods are moved to ''Provider'' interface. Interface methods are '''public''' and this might seem like a contradiction to [[ClarityOfAccessModifiers]]. However, it is not. The instances of ''Provider'' interface are not accessible to [[ClientAPI|clients]] of the [[API]]. They are hidden and only useful for the ''create'' factory method that turns them into ''NonMixed'' instances. As such they are ''single meaning'' methods in an [[ImplementOnlyInterface]] with only one message: ''implement me, don't call me!''. Their [[clarity]] is kept.

There is also the ''Callback'' class which holds originally '''protected final''' methods. It is a final class, with non-public constructor, so its creation is fully under the control of the ''NonMixed'' [[API]] infrastructure. Clients of the ''NonMixed'' class cannot get access to it - the reference is only available to the ''Provider'' interface via the ''initialize'' method. As such its use is ''protected'', only ''Provider'' interface implementor can call its methods. Moreover the class is final and as such its methods have only single meaning: ''call me, if you are implementing the provider''. Fully [[Clarity|clear]] again.

There is also the ''Callback'' class which holds originally '''protected final''' methods. It is a final class, with non-public constructor, so its creation is fully under the control of the ''NonMixed'' [[API]] infrastructure. Clients of the ''NonMixed'' class cannot get access to it - the reference is only available to the ''Provider'' interface via the ''initialize'' method. As such its use is ''protected'', only ''Provider'' interface implementor can call its methods. Moreover the class is final and as such its methods have only single meaning: ''call me, if you are implementing the provider''. Fully [[Clarity|clear]] again.

This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of more correct, but slightly more complex elimination:

<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>

<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>

The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity|clear]] ones. Yet the result is still not ideal. Something is missing.

The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity|clear]] ones. Yet the result is still not ideal. Something is missing.

This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

This essay en-lights what it is. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

It is easy to [[evolution|evolve]] the ''Callback'' contract as well. It is also '''final''' and as such adding new methods there is OK. And new methods in ''Callback'' class is exactly what the [[ProviderAPI|providers]] of the ''Provider'' interface may need in future.

It is easy to [[evolution|evolve]] the ''Callback'' contract as well. It is also '''final''' and as such adding new methods there is OK. And new methods in ''Callback'' class is exactly what the [[ProviderAPI|providers]] of the ''Provider'' interface may need in future.

Also the [[evolution]] of ''Provider'' interface is possible and easy. Adding new methods into subclassable types is of course not [[BackwardCompatibility|backward compatible]] at all, but one can always create new interfaces like ''ExtraProvider''. Because of [[DelegationAndComposition]] this addition has no effect on [[ClientAPI]] - the ''NonMixed'' class does not need to change at all. The only thing that may need to be added is new [[factory]] method for each new interface. But that is quite well thought [[evolution|evolution plan]].

Also the [[evolution]] of ''Provider'' interface is possible and easy. Adding new methods into subclassable types is of course not [[BackwardCompatibility|backward compatible]] at all, but one can always create new interfaces like ''ExtraProvider''. Because of [[DelegationAndComposition]] this addition has no effect on [[ClientAPI]] - the ''NonMixed'' class [[API]] does not need to change at all. The only thing that may need to be added is new [[factory]] method for each new interface. But that is quite well thought [[evolution|evolution plan]].

<comments/>

<comments/>

[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns]]

[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns]] [[Category:APIDesignPatterns:Evolution]]

[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns:Clarity]]

[[Category:APIDesignPatterns:Clarity]] [[Category:APIDesignPatterns]]

=== [[Clarity]] for [[ClientAPI|Clients]] ===

=== [[Clarity]] for [[ClientAPI|Clients]] ===

Clients that hold reference to ''NonMixed'' class see only its '''public''' methods in [[Javadoc]], IDE code completion, etc. They are not distracted by details useful only for providers. The code that [[ClientAPI|callers]] need to provide is completely the same as in the original ''Mixed'' class - e.g. we achieved [[clarity]] for [[ClientAPI|callers]] without complicating their code even a bit (see the calls in the example in following section)!

Clients that hold reference to ''NonMixed'' class see only its '''public''' methods in [[Javadoc]], IDE code completion, etc. They are not distracted by details useful only for providers. The code that [[ClientAPI|callers]] need to provide is absolutelly same as the one when using the original ''Mixed'' class - e.g. we achieved [[clarity]] for [[ClientAPI|callers]] without complicating their code even a bit (see the calls in the example in following section)!

=== [[Clarity]] for [[ProviderAPI|Implementors]] ===

=== [[Clarity]] for [[ProviderAPI|Implementors]] ===

This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>

<source lang="java" snippet="design.sidemeanings.arith.sumTwo"/>

The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity|clear]] ones. Yet the result is still not ideal. Something is missing.

The fuzziness is all around us, including our [[API]]s. The essay [[ClarityOfAccessModifiers]] explains the importance of correct choice of access modifiers. The [[EliminateFuzzyModifiers]] gives a recipe to turn those fuzzy meanings into [[clarity|clear]] ones. Yet the result is still not ideal. Something is missing.

This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is a shorter version.

This essay en-light what is it. More on the topic can be found in [[Cooperating_with_Other_APIs|Chapter 10]] of [[TheAPIBook]]. Here is alternative online version.

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination:

The result of [[EliminateFuzzyModifiers|elimination of public, protected and public abstract]] can be triplication of each fuzzy method. This may not be bad in all times, for example [http://java.sun.com/javase/6/docs/api/java/nio/charset/CharsetDecoder.html CharsetDecoder] successfully provides duplicated versions of its methods (one for [[ClientAPI]] users and one for [[ProviderAPI|providers]] subclassing the class), but on the other hand this is definitely distracting. Here is an example of correct, but complex elimination: