PatternDistributor (BandM signal & music)

java.lang.Object
- eu.bandm.tscore.base.PatternDistributor

```
public class PatternDistributor
extends Object
```
Looks for repettions of a pattern in a certain parameter track and distributes it event-wise to the successor events.

Usage: An instance is constructed. Then it is applied to a Vox object by calling process(Vox) before any further processing of the voice data. Afterwards the parameter texts in the Vox object are adjusted accordingly and can be processed as usual (by applying Translet parsers, etc.)

Distribution is event-wise, means it does not look at any timing, and operates BEFORE any parsing of the parameter text, i.e. as a RAW text level pre-processor. The definition of a repeated pattern is started by a dedicated symbol prepended to the normal parameter values. (This sign defaults to "$").
The parameter text of all subsequent events (upto pattern end) form the pattern.
The end of the pattern definition is the start of its usage, indicated by a certain start marker, which defaults to "IDEM".
The end of the usage may be anywhere. It is caused by any explicit parameter value (possibly starting a new pattern), or by a special marker, which defaults to "TERM".
The repetition can be resumed after a certain pause: By the start marker again, it will start from its beginning, or by a special marker (which defaults to "CONT") it will resume with the same phase as its preceding use had been terminated.
All these special markers (but not the patter definition lead in) must be the only contents of the event's parameter.
The patterns are collected and distributed in their textual representation, i.e. without and prior to any analysis.
The behaviour can be depicted by the following state machine:
```
    start---> [INIT]
                 |
                 | "$xxx"
                 V
      ----->  [COLLECTING] <--------
      ^^        |  |         ________ ) "$xxx"
      ||        |  |"IDEM"                             
      ||        |  |                               
      ||"$yyy"  |  V      (starting from 0) <----
      ||____    |[USING]_________________________) "IDEM"  
      |         |  |     <------------          
      |         |  |                  |   
      |   "TERM"|  |                  |   
      |         |  |"TERM"/"zzz"      |
      |"$yyy"   V  V                  | "CONT"/"IDEM"
      ------- [SUSPENDED] ------------/            
```

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class PatternDistributor.Phase
States of the state machine.

Nested Classes
Modifier and Type	Class and Description
`static class`	`PatternDistributor.Phase` States of the state machine.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`default_endUse` Default for `endUse`
`static String`	`default_resumeUse` Default for `resumeUse`
`static String`	`default_startDef` Default for `startDef`
`static String`	`default_startUse` Default for `startUse`
`protected String`	`endUse` String constant ending the use of the pattern, when parsed in the parameter track.
`protected MessageReceiver<SimpleMessage<XMLDocumentIdentifier>>`	`msg` The drain of error messages
`protected String`	`paramName` Name of the parameter track to process.
`protected List<CheckedList<CheckedPair_LR<Location<XMLDocumentIdentifier>,String>>>`	`pattern` Store for the parameter values which make up the pattern.
`protected int`	`patternphase` Current counter for re-playing the pattern.
`protected PatternDistributor.Phase`	`phase` State of the state machine, modelling recording and playback.
`protected String`	`resumeUse` String constant ending the use of the pattern, when parsed in the parameter track.
`protected String`	`startDef` String constant starting the definition/recording of a pattern
`protected int`	`startDef_length` Holds the string length of `startDef`, for conenience.
`protected String`	`startUse` String constant starting the use of the pattern, when parsed in the parameter track.

Constructor Summary

Constructors
Constructor and Description
`PatternDistributor(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, String pname)` Constructor with default string values for the keywords.
`PatternDistributor(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg, String pname, String startDef, String startUse, String endUse, String resumeUse)` Constructor with explicit string values for the keywords.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`adjust(Event ev)` Remove the "start pattern definition" prefix `startDef` from the parameter source text.
`protected void`	`copyFromPattern(Event ev)` Copy the parameter value back into the voice from the current pattern position.
`protected void`	`copyIntoPattern(Event ev)` Record the parameter value back fromt the voice into the pattern.
`(package private) void`	`exclusiveCheck(Location<XMLDocumentIdentifier> location, String paramName, String keyword, String input)` Raises an error iff the keyword is not the only contents of the parameter source text.
`void`	`process(Vox v)` Service access point: Process this voice and replace the pattern keywords in its parameter track (with the name given when creating this instance) by pattern expansion.
`protected void`	`startUsing(Event ev, String ptext, Location<XMLDocumentIdentifier> loc, String keyword, boolean reset)` Start with the given event the re-play of the pattern.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - msg
```
protected final MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg
```
    The drain of error messages
  - paramName
```
protected final String paramName
```
    Name of the parameter track to process.
  - startDef
```
protected final String startDef
```
    String constant starting the definition/recording of a pattern
  - startDef_length
```
protected final int startDef_length
```
    Holds the string length of startDef, for conenience.
  - startUse
```
protected final String startUse
```
    String constant starting the use of the pattern, when parsed in the parameter track.
  - endUse
```
protected final String endUse
```
    String constant ending the use of the pattern, when parsed in the parameter track.
  - resumeUse
```
protected final String resumeUse
```
    String constant ending the use of the pattern, when parsed in the parameter track.
  - default_startDef
```
public static final String default_startDef
```
    Default for startDef
    
    See Also:
    
    Constant Field Values
  - default_startUse
```
public static final String default_startUse
```
    Default for startUse
    
    See Also:
    
    Constant Field Values
  - default_endUse
```
public static final String default_endUse
```
    Default for endUse
    
    See Also:
    
    Constant Field Values
  - default_resumeUse
```
public static final String default_resumeUse
```
    Default for resumeUse
    
    See Also:
    
    Constant Field Values
  - pattern
```
protected List<CheckedList<CheckedPair_LR<Location<XMLDocumentIdentifier>,String>>> pattern
```
    Store for the parameter values which make up the pattern.
  - patternphase
```
protected int patternphase
```
    Current counter for re-playing the pattern.
  - phase
```
protected PatternDistributor.Phase phase
```
    State of the state machine, modelling recording and playback.
- Constructor Detail
  - PatternDistributor
```
public PatternDistributor(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
                          String pname)
```
    Constructor with default string values for the keywords.
    
    Parameters:
    
    msg - the drain for the error messages.
    
    pname - the name of the parsameter track to process.
  - PatternDistributor
```
public PatternDistributor(MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msg,
                          String pname,
                          String startDef,
                          String startUse,
                          String endUse,
                          String resumeUse)
```
    Constructor with explicit string values for the keywords.
    
    Parameters:
    
    msg - the drain for the error messages.
    
    pname - the name of the parameter track to process.
- Method Detail
  - copyFromPattern
```
protected void copyFromPattern(Event ev)
```
    Copy the parameter value back into the voice from the current pattern position.
  - copyIntoPattern
```
protected void copyIntoPattern(Event ev)
```
    Record the parameter value back fromt the voice into the pattern.
  - adjust
```
protected void adjust(Event ev)
```
    Remove the "start pattern definition" prefix startDef from the parameter source text. (This includes adjustment of the location.) This is destructive: The event object will be altered. FIXME ginge auch NUR auf "pattern" !?!?!
  - exclusiveCheck
```
void exclusiveCheck(Location<XMLDocumentIdentifier> location,
                    String paramName,
                    String keyword,
                    String input)
```
    Raises an error iff the keyword is not the only contents of the parameter source text.
  - startUsing
```
protected void startUsing(Event ev,
                          String ptext,
                          Location<XMLDocumentIdentifier> loc,
                          String keyword,
                          boolean reset)
```
    Start with the given event the re-play of the pattern.
    
    Parameters:
    
    ev - the current event
    
    ptext - the input value for this parameter (for error messageing only)
    
    loc - the location of the parameters input text (for error messageing only)
    
    keyword - the keyword found in the source text (for error messageing only)
    
    reset - whether to start with the beginning of the pattern, not to resume it.
  - process
```
public void process(Vox v)
```
    Service access point: Process this voice and replace the pattern keywords in its parameter track (with the name given when creating this instance) by pattern expansion.

Class PatternDistributor

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

msg

paramName

startDef

startDef_length

startUse

endUse

resumeUse

default_startDef

default_startUse

default_endUse

default_resumeUse

pattern

patternphase

phase

Constructor Detail

PatternDistributor

PatternDistributor

Method Detail

copyFromPattern

copyIntoPattern

adjust

exclusiveCheck

startUsing

process