From f1cd420b51d5aff43301a8c88984d27aecaf21a0 Mon Sep 17 00:00:00 2001 From: Lennart Hensler Date: Wed, 8 Apr 2015 14:38:04 +0200 Subject: [PATCH] Wrote the section about how to add completely new data types --- wiki/typical-data-mining-scenarios.md | 43 ++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/wiki/typical-data-mining-scenarios.md b/wiki/typical-data-mining-scenarios.md index 0ad8a445468..8bd42ea2d8b 100644 --- a/wiki/typical-data-mining-scenarios.md +++ b/wiki/typical-data-mining-scenarios.md @@ -18,4 +18,45 @@ * Create empty properties files for each supported language with the name scheme `_` * Create a `ResourceBundleStringMessages` in the `DataMiningBundleService` * The `ResourceBundleStringMessages` needs the resource base name, which should be `/` - * A reference to this `ResourceBundleStringMessages` should be returned by the method `getStringMessages()` \ No newline at end of file + * A reference to this `ResourceBundleStringMessages` should be returned by the method `getStringMessages()` + +## Adding a completely new Data Type + +A data type is an elementar unit on which the processing components operate. A data type is normally based on a domain element (like `GPSFixMoving` or `TrackedLegOfCompetitor`) and provides contextual information about the domain element (like the name of the regatta or race) via [Functions](wiki/data-mining-architecture#Data-Mining-Functions). + +### Create the necessary Data Types + +* Create an interface for the domain element. The naming convention for data type interfaces is `HasContext`. + * If `TrackedLegOfCompetitor` would be the domain element, then the name of the data type interface should be `HasTrackedLegOfCompetitorContext`. +* Create a data type interface for the steps from the data source to the domain element + * In the case of the `TrackedLegOfCompetitor` the steps would be + * `RacingEventService` + * `LeaderboardGroup` + * `Leaderboard` + * `TrackedRace` + * `TrackedLeg` + * `TrackedLegOfCompetitor` + * This isn't mandatory for the framework to work, but it improves its performance, because it's possible to build a processor chain, that filters after each step. +* Add the data type interfaces to the `Classes` return by the method `getClassesWithMarkedMethods()` of the `DataMiningBundleService`. +* Add methods to get the contextual information and annotate them, so that they get registered as functions. + * To get the contextual data of a higher level data type interface annotate the getter for this interface with `@Connector(scanForStatistics=false)` + * There's currently no parameter support for functions, except for signatures exactly like `(Locale, ResourceBundleStringMessages)`. + * Cycles in the graph of annotated methods aren't supported and would result in an infinite loop during the function registration. + * See [Data Mining Functions](wiki/data-mining-architecture#Data-Mining-Functions) for detailed information about the annotations. +* Implement the data type interfaces. The naming convention for data type classes is `WithContext`. + * If `TrackedLegOfCompetitor` would be the domain element, then the name of the data type class should be `TrackedLegOfCompetitorWithContext`. + +### Implement the Retrieval Processors and define the Retriever Chain + +* Add a `DataSourceProvider` to the `DataMiningBundleService`, if it doesn't contain one for the data source of the data type. +* Implement a retrieval processor for each data type. + * Retrieval processors should extend `AbstractSimpleRetrievalProcessor` + * Retrieval processors used by retriever chains need a constructor with the signature `(ExecutorService, Collection>)` + * A retrieval processor describes how to get from the input data type (like `RacingEventService` or `TrackedRace`) to the result data type (like `TrackedLeg`) with the method `retrieveData`. +* Create a `DataRetrieverChainDefinition` and add it to the `DataMiningBundleService` + * A retriever chain is created with its methods `startWith`, `addAfter` and `endWith`, that add `Classes` of your retrieval processors to the chain. + * Each method has a parameter for the `Class` of the retrieved data type of the next step and some also have a parameter for the `Class` of the retrieval processor of the previous step to ensure type safety. + * Each method has a parameter for a message key, that is needed for the internationalization of the chain + * The call order of these methods has to match `startWith addAfter* endWith` or an exception will be thrown. + * Every retrieval processor needs a constructor with the signature `(ExecutorService, Collection>)` or an exception will be thrown + * See [Defining and building a Data Retriever Chain](wiki/data-mining-architecture#Defining-and-building-a-Data-Retriever-Chain) for examples and more detailed information. \ No newline at end of file