This package contains two abstract classes -- {@link com.programmerdan.minecraft.civspy.samplers.ServerMultiDataSampler} or {@link com.programmerdan.minecraft.civspy.samplers.ServerSingleDataSampler} -- one of which must be the superclass of any implementations you want automatically loaded by CivSpy.
Each abstract class defines two constructors but you don't have to implement for both constructors; choose the one that suits your needs.
Samplers can declare their own period, but no guarantee is made in terms of ordering of execution or alignment of samplers; their executions may be offset, in some cases intentionally, even if their period is the same.
A quick introduction to samplers:
Data Samplers
A Data Sampler should quickly sample one or more pieces of data and pass that data along to the {@link com.programmerdan.minecraft.civspy.DataManager}. This data does not need to be aggregate-able, although it is welcome to be so.
- For Samplers that collect aggregation data, use a {@link com.programmerdan.minecraft.civspy.PointDataSample} POJO to store your samples before passing to the DataManager.
- For Samplers that collect periodic data that should not be summation aggregated, use a {@link com.programmerdan.minecraft.civspy.PeriodicDataSample} POJO to store your samples.
Requirements
All implementations of DataSampler must provide a sample implementation.
- If you extend from
ServerMultiDataSampler, your {@link com.programmerdan.minecraft.civspy.samplers.ServerMultiDataSampler#sample} method must return a List of DataSample POJOs.
- If you extend from
ServerSingleDataSampler, your {@link com.programmerdan.minecraft.civspy.samplers.ServerSingleDataSampler#sample} method must return a single DataSample POJO.
All implementations of DataSampler must provide a constructor that takes a DataManager, Logger, String, and optionally a ConfigurationSection as input.
- The {@link com.programmerdan.minecraft.civspy.DataManager} is CivSpy system provided and your code should likely leave it alone to prevent abnormalities.
- The {@link java.util.logging.Logger} is put into protected variable
logger and is available to subclasses to write exceptional circumstances to the log (do not log on every execution of your sampler!).
- The String is the value that will be returned by
getServer. Note while you don't have to pass this value along to the superclass, it is strongly recommended, and regardless the parameter must exist on your constructor.
- (optional) The {@link org.bukkit.configuration.ConfigurationSection} is the configuration for your Sampler as defined in the
config.yml file. The _simple name_ of your class determines which section to extract and pass along. So if you Sampler is called PlayerLocationSampler then CivSpy attempts to give the config.yml root-level section of the same name to your Sampler, if a constructor is found that accepts configuration sections.
- If you want to override the default sample period of 1 minute (60,000 ms) call
setPeriod from within your constructor. Subsequent calls to setPeriod will be ignored.
Usage
DataSamples are POJOs -- just construct them via their constructor and don't worry about anything else, they just hold and pass along data.
One parameter on all DataSample constructors is "Server" -- you can get the plugin's configured "Server" name via getServer(). Be sure to include the server name in your DataSampler POJOs -- see the constructor on PointDataSample and PeriodicDataSample. If local or not specified in CivSpy config, this value will be the string literal "local".
Your sampler can turn itself off by calling deactivate -- the sampler is still called on period, but your sample method won't be called, so only do so in case of exceptional circumstance; otherwise, leave activation and de-activation up to CivSpy's management routines.
That's basically it. Pick a Sampler base type to extend from -- either multi-sample or single-sample -- and enjoy.