Reports Generation

Objective

This guide should give you a brief overview how reports are generated. In the first part the ReportsGenerator will be introduced and explained. In the second part the Report creation will be explained (Tag filtering).

ReportsGenerator

The Reports Generator is created with a name for the Reports Generator and a ECSpec. An ECSpec describes an event cycle and one or more reports that are to be generated from it. It contains a list of logical Readers whose read cycles are to be included in the event cycle, a specification of how the boundaries of event cycles are to be determined, and a list of specifications each of which describes a report to be generated from this event cycle. When there are subscribers for the EventCycle the ReportsGenerator starts the EventCycle. When the Event Cycle is finished, each report is generated by the Report class and sent through the ReportsGenerator to the subscribers.

We will give a short overview to the methods available in the ReportsGenerator. For a complete list of all methods refer to the java-doc:

  • ReportsGenerator: The constructor takes a name for the ReportsGenerator and an ECSpec for the later construction of an EventCycle.
  • setState/getState: A ReportsGenerator has an associated state that can be modified by this methods. For further information on the states refer to ReportsGenerator StateDiagram.
  • subscribe/unsubscribe: Whenever a a client subscribes/unsubscribes for an EventCycle through the ALE interface the notificationURI will be registered/deregistered by this methods.
  • getSubscribers: Returns the notification URIs of all subscribers.
  • notifySubscribers: Upon a successfull run of an EventCycle the subscribers need to be notified about the Reports.
  • poll: The ReportsGenerator allows polling. This method performs the polling.
  • getPollReports: This method delivers the ec reports which have been generated because of a poll.

ReportsGenerator StateDiagram

The ReportsGenerator is implemented as a state machine with essentially 3 states. When a ReportsGenerator is created it transitions into the running state and from there directly into one of the two substates REQUESTED or UNREQUESTED depending whether the ALE requestes the ReportsGenerator to deliver tags or not. As long as the ReportsGenerator is not undefined through the ALE it transitions between the states REQUESTED and UNREQUESTED.

  • REQUESTED: There is a client that wants to retrieve Tags. This state implies that there is a running EventCycle.
  • UNREQUESTED: There is no client and the ReportsGenerator is waiting.

Report

The Report generates a Report according to the ECReportSpec. The Report class is invoked by the EventCycle. According to its ECReportSpec. It decides which of the Tags observed or lost by the current or last EventCycle are to be included in the report for a specific group and which not. Responsible for this decision is the isMember(String tagURI) method.

private boolean isMember(String tagURI) 
        throws ECSpecValidationException, ImplementationException {

        if (reportType == ECReportSetEnum.ADDITIONS) {
                
                // if report type is additions the tag is only a 
                // member if it wasn't a member of the last event cycle
                if (lastEventCycleTags.contains(tagURI)) {
                        return false;
                }
                
        }
        
        // check if tagURI is member of an exclude pattern
        for (Pattern pattern : excludePatterns) {
                if (pattern.isMember(tagURI)) {
                        return false;
                }
        }
        
        // check if there are include patterns specified
        if (includePatterns.size() == 0) {
                return true;
        } else {
                
                // check if tagURI is a member of an include pattern
                for (Pattern pattern : includePatterns) {
                        if (pattern.isMember(tagURI)) {
                                return true;
                        }
                }
                return false;
        }
        
}

Reasons for an observed Tag not to be included in the report could be:

  • reportType is set to Aditions: The Tag was not present during the last EventCyle
  • reportType is set to Current: The Tag is member of an exclude pattern

Reasons for an not observed Tag to be included in the report could be:

  • reportType is set to Deletions: The Tag was present during the last EventCycle, but not in the current

If the method isMember(String tagURI) returns with true, then the Tag is put in the Report which every subscriber of the Event Cycle gets by the Reports Generator.