Client API Interface

String getPluginName()

This method gets called whenever Pulseway requires the plugin name for logging, displaying it to the user in the plugins tab and saving settings.

@Override
public String getPluginName()
{
    return "Simple Plugin";
}
    

String getPluginDescription()

GetPluginDescription's main purpose is pretty straight forward; it shows to the user a short descriptive text that represents the main functionality of your plugin.

@Override
public String getPluginDescription()
{
    return "This plugin shows the current date and time.";
}
    

Groups getAdditionalComputerDetails()

In order for Pulseway to actually show anything new to its clients this method gets used. The Groups that get returned will be shown in the computer details page. This is the perfect place to show a plugin main menu with "PageItem" and "CommandItem" that will further be used to lead the user to the data he is looking for.

@Override
public Groups getAdditionalComputerDetails()
{
    Groups container = new Groups();// Group of "Group" types.
    // Group of "SimpleItem" / "CommandItem" / "PageItem" with the title Simple Plugin.
    Group mainGroup = new Group( "Simple Plugin");
    // Simple Item with "Current Date: " title and current date as subtitle.
    SimpleItem date = new SimpleItem( "Current Date: ", SimpleDateFormat.getDateInstance().format(new Date()));
    // Simple Item with "Current Time: " title and current time as subtitle.
    SimpleItem time = new SimpleItem( "Current Time: ", SimpleDateFormat.getTimeInstance().format(new Date()));
    mainGroup.getItems().add(date); // Adding the date SimpleItem to our Group container.
    mainGroup.getItems().add(time); // Adding the time SimpleItem to our Group container.
    container.add(mainGroup); // Adding the mainGroup Group to Groups container.
    return container; // Returning our Groups container to Pulseway.
}

void onCommandReceived(int commandId)

Here is where the action begins. The command got executed and we received the identification number of which command was called.

private final static int COMMAND_INCREASE_INVOCATION_COUNT = 1;
private int invocationCount;

@Override
public void onCommandReceived(int commandId)
{
    if (commandId == COMMAND_INCREASE_INVOCATION_COUNT)
    { 
        invocationCount++;
    }
}
    

void onPluginLoaded()

This method gets triggered when the plugin is fully loaded and ready to start working.

@Override
public void onPluginLoaded()
{
    invocationCount = 0;
}

void setValueForKey(String key, String value)

In order to save plugin's data we can implement our own methods or use "setValueForKey" which saves an entry with the name specified in the "key" parameter and our value safely encrypted.

@Override
public void onPluginLoaded()
{
    setValueForKey("Plugin Configuration", "This plugin shows the current date and time.");
}

String getValueForKey()

getValueForKey is used to get a previously stored value using "setValueForKey". This reads the value, decrypts it and returns it in clear text.

@Override
public String getPluginDescription()
{
    return getValueForKey("PluginDescription");
}

Version getMinimumRequiredAgentVersion()

When your plugin uses a pre-release version of Pulseway and you want to release it, you should specify which is the minimum required version to make sure that everything will work smoothly.

@Override
public Version getMinimumRequiredAgentVersion()
{
    return new Version(2, 9, 1);
}
   

JDialog getConfigurationForm()

If your plugin requires a configuration in order to work then the best approach is having a dialog (a JDialog in our case) which can handle the plugin configuration. This JDialog gets created when the user clicks the "Configure" button inside the "Plugins" tab from Pulseway Manager.

@Override
public JDialog getConfigurationForm()
{
    return new MyConfigurationDialog(this);
}

And the form code:

import javax.swing.JDialog;
import com.mmsoftdesign.client.IDataStore;

public class MyConfigurationDialog extends JDialog
{
    private final IDataStore dataStore;

    public MyConfigurationDialog(IDataStore dataStore)
    {
        this.dataStore = dataStore; 
        initializeComponent();
    } 
}
   

void onPluginDataCheck()

This is where your plugin checks whether it needs to inform you about something, perfect place for notifications to be sent. It gets called automatically every 15-20 seconds.

@Override
public void onPluginDataCheck()
{
    invocationCount++;
}

void sendNotificationToAllDevices(String message, NotificationPriority priority)

Method used to send a notification to all devices that have push notifications enabled. The message can have up to 250 characters to display on the mobile device alert and up to 5000 characters to be viewed inside the Pulseway client.

@Override
public void onPluginDataCheck()
{
    sendNotificationToAllDevices("Current Invocation Count: " + invocationCount, NotificationPriority.NORMAL);
}

boolean canSendNotifications

canSendNotifications is a boolean method that lets you know if you can send a notification (If false it means that there is a notification sent by this plugin that wasn't deleted from the client application.

@Override
public void onPluginDataCheck()
{
    if (canSendNotifications())
    {
        sendNotificationToAllDevices("Current Invocation Count: " + invocationCount, NotificationPriority.NORMAL);
    }
}

void onNotificationDeleted()

If your plugin has to send a notification and you canSendNotifications() returns false then you need to use a Queue (Or any other collection) to store unsent notifications and when we get the signal that we can send a new notification to send the next one on our list.

private final Queue<String> notificationQueue = new LinkedBlockingQueue<String>();

@Override
public void onPluginDataCheck()
{
    String message = "Current Invocation Count: " + invocationCount;
    if (canSendNotifications())
    {
        sendNotificationToAllDevices(message, NotificationPriority.NORMAL);
    }
    else
    {
        notificationQueue.add(message);
    }
} 

@Override
public void onNotificationDeleted()
{
    sendNotificationToAllDevices(notificationList.poll(), NotificationPriority.NORMAL);
}

ComputerInfo GetComputerInfo()

Sometimes having more information about local computer is crucial so Pulseway API makes sure you have all the data you need to know in real time. ComputerInfo type stores 3 things:

• boolean isInMaintenanceMode(): If true than Maintenance Mode is enabled (that means that all notifications will not be sent).
• String getName(): The name of the computer that was set in Pulseway Manager.
• String getGroup(): The group of the computer that was set in Pulseway Manager.

@Override
public void onPluginDataCheck()
{
    ComputerInfo localComputer = gGetComputerInfo();

    if (canSendNotifications() && !localComputer.isInMaintenanceMode())
    {
        sendNotificationToAllDevices("Current Invocation Count: "+invocationCount+
        "\nSent from: "+ localComputer.getName()+ 
        "\nIn Group: "+localComputer.getGroup(),NotificationPriority., NORMAL);
    }
}

void onPluginUnloaded()

This is used called right after the plugin is marked for removal and gives you a chance to disconnect active connections or perform cleanup procedures.

@Override
public void onPluginUnloaded()
{
    MyDatabaseConnection.Close();
    MyDatabaseConnection.Dispose();
}

Groups getPageDetails(int pageId)

Occurs when a PageItem gets called by a client and asks for its Groups content.

private final static int PAGE_COMPUTER_DETAILS = 1;
private final static int PAGE_COMMAND_RESET_INVOCATION_COUNT = 1;

@Override
public Groups getPageDetails(int pageId)
{
    if (pageId != PAGE_COMPUTER_DETAILS)
    {
        return null; 
    }

    Groups container = new Groups();
    ComputerInfo localComputer = getComputerInfo();
    Group mainGroup = new Group ("Computer Details");
    SimpleItem name = new SimpleItem("Computer Name: ", localComputer.getName());
    SimpleItem group = new SimpleItem("Computer Group: ", localComputer.getGroup());
    SimpleItem maintenance = new SimpleItem("Computer Maintenance: ", Boolean.toString(localComputer.isInMaintenanceMode()));
    CommandItem command = new CommandItem(PAGE_COMMAND_RESET_INVOCATION_COUNT, "Reset Invocation Count");
    mainGroup.getItems().add(name);
    mainGroup.getItems().add(group);
    mainGroup.getItems().add(maintenance);
    container.add(mainGroup);
    return container;
}

void onPageCommandReceived()

onPageCommandReceived is not the same thing with onCommandReceived. All CommandItems that are triggered from inside a PageItem will trigger onPageCommandReceived and all CommandItems that are called from the getAdditionalComputerDetails will trigger onCommandReceived.

@Override
public void onPageCommandReceived(int pageId, int commandId)
{
    if (pageId != PAGE_COMPUTER_DETAILSM && commandId != PAGE_COMMAND_RESET_INVOCATION_COUNT)
    {
        return;
    }
    invocationCount = 0;
}

void trace(String logMessage)

Method used for debugging purposes.When called the logMessage text will be written in the log file.

@Override
public void onPageCommandReceived(int pageId, int commandId)
{
    if (pageId != PAGE_COMPUTER_DETAILS && commandId != PAGE_COMMAND_RESET_INVOCATION_COUNT)
    {
        trace("PageCommandReceived has unknown ids: "+pageId+" - "+commandId);
        return;
    }
    invocationCount = 0;
}

void onDateInputValueChanged(String inputId, Date inputValue)

Method that will be called whenever an DateInput's value has changed. The Date type contains the year, month and day sent from the mobile client.

@Override
public void onDateInputValueChanged(String inputId, Date inputValue) 
{
    System.out.println("Got date: " + Integer.toString(inputValue.getYear()) + " " + Integer.toString(inputValue.getMonth()) + " " + Integer.toString(inputValue.getDay()));
}

void onTimeInputValueChanged(String inputId, Time inputValue)

Method that will be called whenever an TimeInput's value has changed. The Time type contains the hour and minute sent from the mobile client.

@Override
public void onTimeInputValueChanged(String inputId, Time inputValue) 
{
    System.out.println("Got time: " + Integer.toString(inputValue.getHour()) + " " + Integer.toString(inputValue.getMinutes()));
}

void onDateTimeInputValueChanged(String inputId, DateTime inputValue)

Method that will be called whenever an DateTimeInput's value has changed. The DateTime type contains the year, month, day, hour and minute sent from the mobile client.

@Override
public void onDateTimeInputValueChanged(String inputId, DateTime inputValue)
{
    System.out.println("Got datetime: " + Integer.toString(inputValue.getYear()) + " " + Integer.toString(inputValue.getMonth()) + " " + Integer.toString(inputValue.getDay()) + " " + Integer.toString(inputValue.getHour()) + " " + Integer.toString(inputValue.getHour()));
}

void onNumericInputValueChanged(String inputId, int inputValue)

Method that will be called whenever an NumericInput's value has changed. The inputValue type contains the number sent from the mobile client.

@Override
public void onNumericInputValueChanged(String inputId, int inputValue)
{
    changeMe = inputValue;
}

void onTextInputValueChanged(String inputId, String inputValue)

Method that will be called whenever an TextInput's value has changed. The inputValue type contains the text sent from the mobile client.

@Override
public void onTextInputValueChanged(String inputId, String inputValue)
{
    System.out.println("Got text: " + inputValue);
}

void onPickListInputValueChanged(String inputId, int pickListItemId)

Method that will be called whenever an PickListInput's selected item has changed. The pickListItemId represents the ID of the PickListItem.

@Override
public void onPickListInputValueChanged(String inputId, int pickListItemId)
{
    System.out.println("Picked Item Id: " + Integer.toString(pickListItemId));
}