net.sf.mmm.util.component.api

Interface Api

public interface Api

This interface only exists for documentation purpose!
API is a shortcut for Application Programming Interface and identifies all types required to access a component. The main idea is to abstract from the implementation of the component so it gets replaceable and the design is maintainable.
The most important type in Java to define an API is the interface. However an API may also consist of Enum types or Pojo classes and Datatypes that are accepted as arguments by an interface. The actual API of a component is therefore the combination of all these types. It has to be self-contained what means that it only contains references to types legally considered as part of the API. With references we are NOT talking about JavaDoc-links.
A typical negative example is an interface that references objects from the implementation. That is bad design as the idea of the API is to abstract from the implementation.
Please also note that the API will typically have references to common java Datatypes such as String, Long, etc. as well as Collections especially List. All these types are considered as legal parts that do NOT influence if API is considered as self-contained.
We strongly recommend to define sub-packages named api for your components that define the actual API (see Developer-Guide of this project). This allows easy checking if your code is following architectural guidelines via the full-qualified references (typically in import statements). Within this context it is also important to consider dependencies between components. Therefore it is very important to consider the following guidelines:

• The application architecture has to define the components AND the dependencies between them.
• You need to distinguish between the technical architecture defining application layers and their dependencies and the business architecture defining slices (business components that are orthogonal to the layers).
• Cyclic dependencies between components indicate a bad design and are prohibited.
• The proper tailoring of a large scope into components is the key to a maintainable application. It is easy to fix a bad component implementation compared to a bad architecture design. This is the main task of the architect and requires a lot of experience that can not be expressed in simple instructions. There are good books on this topic but the most important skills can only be learned by doing (including doing mistakes).
• The code has to follow these rules. All types of a component should only reference types of another component that are part of the API and that follow the allowed dependencies defined by the architecture.
• To ensure that these rules are followed in a large software project, you need tools to support you. Such tools need to show warnings to the developers if they violate the architecture.

Following these rules is key to build high quality software.

Since:

3.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

Cdi

Field Summary

Fields

Modifier and Type	Field and Description
static String	EXTENDABLE_INTERFACE This is used to mark interfaces of the API that may potentially be extended.

Field Detail

EXTENDABLE_INTERFACE

static final String EXTENDABLE_INTERFACE

This is used to mark interfaces of the API that may potentially be extended. With extended we mean that new methods will be added. This is no problem for the user of the interface but for implementors. To prevent implementors from incompatibilities on updates of components provided by this project, we provide abstract base implementations in the base packages that are located as siblings of the api packages. Typically that Class is named like the interface with the prefix Abstract. You are strongly encouraged to extend these base implementations rather than directly implementing the interface to gain compatibility in case of an extension. The latter is still allowed but you have to be aware of the consequences that you may have to fix compile errors after upgrading and your code may NOT work across different releases.
NOTE:
With Java8 default methods can be added to interfaces. This reduces the problem but may not eliminate it. This constant is only for documentation purpose. Please never use it in your code.