Entity Provider External capabilities

Information

This documents the ways to create external capabilities and some of the more prominent examples of them.

External Capabilities creation

External capabilities allow anyone to extend the functionality of the entity system without needing to add their code into the core project. Creation of external capabilities normally requires the use of an adaptor project. This adaptor project would be external to the projects which use the capability and also external to the projects which define the entity set it is related to. This way it is possible to leave out this capability and still have all projects function without creating a dependency web. More info about this on Adaptor projects.

If you do not have a project which defines an entity set then you either need to use someone elses or create one. For this example, we will assume we have a project (widgetmaker) which defines the widget entities. It is a simple entity set and only implements the CoreEntityProvider.

Define the widget attaching functionality in the widgetmaker service (implement the code which supports the attaching of widgets)

public WidgetMakerService {
...
   public void attachWidget(String reference, Widget widget);

   public List<Widget> getAttachedWidgets(String reference);
}

Create an Adaptor project for the new external capability. This project should depend on ONLY the entitybroker and widgetmaker.
Define the new WidgetAttacher capability by extending EntityProvider
- This widget attacher allows someone to make it so their entities can have widgets attached to them
- It would be undesirable to force the widgetmaker into the kernel just so that entities could potentially support the attaching of widgets for many reasons (it is beta, it does not perform well enough, it is not a functionality that is widely desired, etc.) so the adapator allows us to have the flexibility of extending without requiring
```
/**
 * Allow your entities to have widgets attached to them, capabilities extension of the entitybroker system
 */
public interface WidgetAttacher extends EntityProvider {
    // this space left intentionally blank
}
```
- You should have lots of comments, I omitted them here for readability
- Note that it is ok to include the Widget object from the widgetmaker project because it is a dependency
Wire in the capability by checking for providers which use this capability
1. Inject the EntityProviderManager which allows you to get to EntityProviders which are implementing your capability