Prism

API

    There are three ways plugins can work with Prism:

    • Using the API to read information
    • Firing custom events that communicate custom action/events to be logged
    • Listening to internal Prism events (currently in development)

    Prism - JavaDoc

    API

    The API allows plugins to query the database just like a lookup would. Instead of supplying the parameters through commands, you do it through code.

    Click here for a full API example

    Notes

    When running a lookup/rollback/restore yourself, please be sure to keep them in async threads when possible. If the main thread has to wait for database calls, etc, it may stall/lag.

    Bukkit makes this easy - just run the code inside of a ...

    plugin.getServer().getScheduler().runTaskAsynchronously(plugin, new Runnable(){
      public void run(){
      }
    }
    

    ...method

    Lookups

    After loading Prism, create an instance of QueryParameters - this allows you to define all of the conditions that appliers allow.

    QueryParameters parameters = new QueryParameters();

    Here are a few examples of many parameters you may set:

    World name:

    parameters.setWorld("world");

    Action type. Either original or third party actions supported.

    parameters.addActionType("block-break");

    Limit the results:

    parameters.setLimit(100);

    Then, you need to create an instance of the ActionsQuery class:

    ActionsQuery aq = new ActionsQuery(prism);

    And run the query:

    QueryResult lookupResult = aq.lookup( parameters );

    The QueryResult class contains information about the query - most importantly, the results. Look at the code example linked to above to see how to iterate the results.

    The query system will use Prism's existing database pooling system, you do not need to establish any database connections.

    Rollback/Restore

    You can apply rollback/restore actions as well using the same QueryParameter object, and if there are results, calling:

    Rollback rb = new Rollback( plugin.getPrism(), player, lookupResult.getActionResults(), parameters, new DemoApplierCallback() );
    rb.apply();
    

    We recommend running this

    The DemoApplierCallback class is an optional customization you can make to handle the results of the applier. The default prism applier will display messages to the player containing the count of the total changes and lines skipped, etc.

    Manually Logging Events

    Sometimes your plugin has to cancel an event, but you still want it recorded. You can manually build a Prism action object using the Factory.

    It's in need of better documentation but you can use the ActionFactory class to create the Prism object, and then pass it to the queue.

    Here's an example: Manual ItemStack Action

    Custom Events

    You can register custom events with Prism. These are events that are unique to your plugins. For example, DarkMythos has a "spell-found" event for when players discover spell books.

    First, register the new action type:

    try {
      Prism.getActionRegistry().registerCustomAction( this, new ActionType( "pr-api-demo", false, true, false, "DemoHandler", "triggered" ) );
    } catch (InvalidActionException e) {
      // If something you register is incorrect, Prism will let you know in e.getMessage();
      e.printStackTrace();
    }
    

    When ready, manually trigger the event

    PrismCustomPlayerActionEvent prismEvent = new PrismCustomPlayerActionEvent( plugin, "pr-api-demo", player, null );
    plugin.getServer().getPluginManager().callEvent(prismEvent);
    

    Prism will listen for the event and when detected, it will record a pr-api-demo action to the database.

    You can manually record the event as well, if you prefer.

    Custom Event Rollback/Restore Handling

    You may register custom events with Prism. These allow you to have Prism track special events that you have control over rollback/restores of.

    For example, you can log a money transaction, and your handler could provide Prism with custom logic to rollback the transaction when someone runs pr rb on the event.

    Define an Action glass that extends GenericAction. Any of the methods in this class can be overridden but essentially, you'll only need to customize getNiceName, applyRollback and/or applyRestore

    Once you have a handler defined, you can register it with Prism:

    try {
      Prism.getHandlerRegistry().registerCustomHandler( this, DemoHandler.class );
    } catch (InvalidActionException e) {
      e.printStackTrace();
    }
    

    Prism Process Events

    Prism fires several internal events in case you want to listen for changes.

    PrismBlocksRollbackEvent, PrismBlocksDrainEvent, PrismBlocksExtinguishEvent

    If you listen to the event, it contains:

    getBlockStateChanges - A list of all block state changes in the process.

    onBehalfOf - The name of the player who did it.

    getRadius - The radius used.

    The rollback event also contains method getQueryParameters, which describes the query parameter object used.

    Custom Parameters

    Requires Prism 2.0

    You can extend the available parameters by implementing PrismParameterHandler and registering your handler with Prism.

    First, create a class that implements the PrismParameterHandler interface:

    public class IdParameter implements PrismParameterHandler {
    
        public String getName(){
                return "Id";
        }
    
        public Pattern getArgumentPattern(){
               return Pattern.compile("(id):([0-9]+)");
        }
    
        public void process( QueryParameters query, Matcher input, CommandSender sender ){
            if( !TypeUtils.isNumeric( input.group(2) ) ){
                throw new IllegalArgumentException("ID must be a number. Use /prism ? for help.");
            }
            query.setId( Integer.parseInt(input.group(2)) );
        }
    }
    

    Prism will pass in the QueryParameters query-building object, a Matcher object that contains the matching parameter Strings, and the sender. Be aware, the sender may be null if parameters are matching via purge commands, etc.

    You can define custom logic for populating the query builder. Any IllegalArgumentException thrown from the handler will cause the parameter processor to stop and display the error to the user.

    Register the handler, along with a regular expression pattern defining what parameter will be checked:

    Prism.registerParameter(new IdParameter());

    Prism will check every argument individually, meaning Prism will split a:break p:player into two arguments and find the matching handler for each.

    The (id):([0-9]+) regex will match the id:5 style Prism parameter. It requires a the parameter of id and an input value that's a number.

    The matching values will be provided to your handler as the Matcher. If Prism is in debug mode, it will print the matches it's found for easier debugging.

    If you stick with the traditional parameter syntax, the parameter will be input.group(1) and the value will be input.group(2). All default Prism handlers use this same method, so you can look at those for an example.

    Wiki markup to link to this page: [[api]] or [[api|API]]