Pages

other-information/API for other plugins

API for other plugins

Logging Data

It is incredibly easy for other plugins to log their own data to HawkEye so that server owners can see as much information as possible about their server. It takes one import and a single line of code for basic usage.

  1. Add HawkEye.jar as an External Jar in your IDE.
  2. Import uk.co.oliwali.HawkEye.util.HawkEyeAPI into any classes where you want to log to HawkEye.

When you want to log something, use the method:

HawkEyeAPI.addCustomEntry(JavaPlugin plugin, String action, Player player, Location location, String data);

Use the action parameter to differentiate between different types of actions your plugin logs. Use only alphanumeric characters and spaces in your action names.



Basic Example using a 'Home' plugin

The following logs to HawkEye everytime a player 'goes home'. It logs the 'data' part as the ID of the home in the database. Please note that the following will force your users to use HawkEye (it doesn't check if the plugin is loaded or not).

    private void goHome(Player player, Home home) {
        Location loc = home.getLocation();
        player.teleport(loc);
        HawkEyeAPI.addCustomEntry(this, "Go Home", player, loc, home.getId());
    }

Other uses of the data field could be for the ban reason in a ban plugin or winner of the fight in a war plugin, for example.



Advanced example that checks if HawkEye is loaded

This example checks if HawkEye exists first, making it optional for your plugin users.

    public class MultiHome extends JavaPlugin {

        public boolean usingHawkEye = false;

        public void onEnable() {
            Plugin dl = getServer().getPluginManager().getPlugin("HawkEye");
            if (dl != null)
                this.usingHawkEye = true;
        }

        private void goHome(Player player, Home home) {
        Location loc = home.getLocation();
        player.teleport(loc);
        if (this.usingHawkEye) HawkEyeAPI.addEntry(this, "Go Home", player, loc, home.getId());
    }


Logging normal HawkEye events

he normal HawkEye events like block breaks can all be logged from the API too. Simply use this API method instead:

HawkEyeAPI.addEntry(JavaPlugin plugin, DataType type, Player player, Location location, String data);

DataType is located at uk.co.oliwali.HawkEye.DataType






Retrieving data

Retrieving data is a little bit more complicated than adding to the database. You need to create your own 'callback' object for the search engine to call once it is done retrieving results. The basic method you need to call is this:

HawkEyeAPI.performSearch(BaseCallback callBack, SearchParser parser, SearchDir dir);



Creating a BaseCallback class

To perform a search you need to use an instance of a class extending BaseCallback. There are two built-in callbacks that you can use if need be, although they are designed for very specific uses inside HawkEye. These can be found in the callbacks package: uk.co.oliwali.HawkEye.callbacks.

You will more than likely need to create your own BaseCallback class. This class is outlined here:

public abstract class BaseCallback {
		
	/**
	 * Contains results of the search. This is set automatically before execute() is called
	 */
	public List<DataEntry> results = null;
		
	/**
	* Called when the search is complete
	 */
	public abstract void execute();
		
	/**
	* Called if an error occurs during the search
	*/
	public abstract void error(SearchError error, String message);
	
}

Here is an example of a very simple extension of BaseCallback

    public class SimpleSearch extends BaseCallback {
        
        private Player player;
        
        public SimpleSearch(Player player) {
            player.sendMessage("Search database...");
        }

        public void execute() {
            player.sendMessage("Search complete. " + results.size() + " results found");
        }
        
        public void error(SearchError error, String message) {
            player.sendMessage(message);
        }

    }


Creating a SearchParser instance

Obviously you need to give the search engine some parameters to build a query out of. This is done by using the SearchParser class, found here: uk.co.oliwali.HawkEye.SearchParser There are four constructors available. Two are mainly for internal HawkEye commands, whilst the others are more general:

  • public SearchParser() { } - this is the constructor you will most likely use
  • public SearchParser(Player player) { } - use this one if you are searching due to some kind of player input
  • public SearchParser(Player player, int radius) { } - this is used for 'radius' searching in HawkEye
  • public SearchParser(Player player, List<String> args) throws IllegalArgumentException { } - used for HawkEye user-inputted search parameters

SearchParser contains public methods that you can set to whatever you like. They are all optional, but bear in mind if you supply nothing, you won't get any results! The methods are outlined here:

  • public Player player = null; - Player that has called initiated the search somehow
  • public String[] players = null; - Array of player names to search for. Can be partial
  • public Vector loc = null; - Location to search around
  • public Vector minLoc = null; - Minimum corner of a cuboid to search in
  • public Vector maxLoc = null; - Maximum corner of a cuboid to search in
  • public Integer radius = null; - Radius to search around
  • public List<DataType> actions = new ArrayList<DataType>(); - List of DataType actions to search for
  • public String[] worlds = null; - Array of worlds to search for. Can be partial
  • public String dateFrom = null; - Date to start the search from
  • public String dateTo = null; - Date to end the search at
  • public String[] filters = null; - Array of strings to use as filters in the data column

If you set the location and/or radius, you should then call the parseLocations() method to sort out the locations into proper minLoc and maxLoc values. If you set radius but no location and then call parseLocations() you MUST have set player, otherwise you shouldn't have set radius.

Here is an example of a very simple setup of a SearchParser:

    SearchParser parser = new SearchParser();
    parser.player = player;
    parser.radius = 5;
    parser.actions = Arrays.asList({DataType.BLOCK_BREAK, DataType.BLOCK_PLACE});
    parser.parseLocations();

This will search 5 blocks around the player for block breaks and block places


SearchDir

SearchDir is an enumerator representing the direction to list search results in. Simply import the class and specify SearchDir.DESC or SearchDir.ASC



Putting it all together

So now we have got our BaseCallback written and our SearchParser instance created, we just need to put it together:

    //Setup a SearchParser instance and set values
    SearchParser parser = new SearchParser();
    parser.player = player;
    parser.radius = 5;
    parser.actions = Arrays.asList({DataType.BLOCK_BREAK, DataType.BLOCK_PLACE});
    parser.parseLocations();
    
    //Call search function
    performSearch(new SimpleSearch(player), parser, SearchDir.DESC);

This will search 5 blocks around the player for block break and block place. When the search is done the callback class tells the player how many results were found.

Comments

Posts Quoted:
Reply
Clear All Quotes