What are Spark plugins?

myplugin.jar!/
 |- plugin.xml     <- Plugin definition file
 |- libs/          <- Contains all the class archives needed to run this plugin.

<?xml version="1.0" encoding="UTF-8"?>

  <!-- Google Plugin Structure -->
      <plugin>
        <name>Google Desktop Plugin</name>
        <class>com.examples.plugins.GooglePlugin</class>
        <author>Derek DeMoro</author>
        <version>1.0</version>
        <description>Enables users to find files and emails relating to users using Google Desktop technology.</description>
        <email>ddman@jivesoftware.com</email>
        <minSparkVersion>2.6.0</minSparkVersion>
        <os>Windows,Linux,Mac</os>
      </plugin>
      

Spark/
 |- plugins/     <- Put your plugin jar file here
 |- lib/       <- The main classes and libraries needed to run the Spark
 |- resources/ <- Contains other supportive documents and libraries
 |- docs/ <- Help Manuals and the JavaDoc to help you develop your own plugins.

package org.jivesoftware.spark.plugin.example;

import org.jivesoftware.spark.plugin.Plugin;

/**
 * Implements the Spark Plugin framework to display the different possibilities using
 * Spark.
 */
public class ExamplePlugin implements Plugin {

    /**
     * Called after Spark is loaded to initialize the new plugin.
     */
    public void initialize() {
        System.out.println("Welcome To Spark");
    }

    /**
     * Called when Spark is shutting down to allow for persistence of information
     * or releasing of resources.
     */
    public void shutdown() {

    }

    /**
     * Return true if the Spark can shutdown on users request.
     * @return true if Spark can shutdown on users request.
     */
    public boolean canShutDown() {
        return true;
    }

    /**
    * Is called when a user explicitly asked to uninstall this plugin.
    * The plugin owner is responsible to clean up any resources and
    * remove any components install in Spark.
    */
    public void uninstall(){
       // Remove all resources belonging to this plugin.
    }
}

public class ExamplePlugin implements Plugin {
    // ...

    /**
     * Adds a tab to Spark
     */
    private void addTabToSpark(){
         // Get Workspace UI from SparkManager
        Workspace workspace = SparkManager.getWorkspace();
        // Retrieve the Tabbed Pane from the WorkspaceUI.
        JTabbedPane tabbedPane = workspace.getWorkspacePane();
        // Add own Tab.
        tabbedPane.addTab("My Plugin", new JButton("Hello"));
    }

    // ...
}

  private void addContactListListener(){
         // Get Workspace UI from SparkManager
        Workspace workspace = SparkManager.getWorkspace();
        // Retrieve the ContactList from the Workspace
        ContactList contactList = workspace.getContactList();
        // Create an action to add to the Context Menu
        final Action sayHelloAction = new AbstractAction() {
            public void actionPerformed(ActionEvent actionEvent) {
                JOptionPane.showMessageDialog(SparkManager.getMainWindow(), "Welcome to Spark");
            }
        };

        sayHelloAction.putValue(Action.NAME, "Say Hello To Me");


        // Add own Tab.
        contactList.addContextMenuListener(new ContextMenuListener() {
            public void poppingUp(Object object, JPopupMenu popup) {
                if(object instanceof ContactItem){
                    popup.add(sayHelloAction);
                }
            }

            public void poppingDown(JPopupMenu popup) {

            }

            public boolean handleDefaultAction(MouseEvent e) {
                return false;
            }
        });
    }

    private void addContactListenerToChatRoom() {
       // Retrieve a ChatManager from SparkManager
        ChatManager chatManager = SparkManager.getChatManager();

        final ContextMenuListener listener = new ContextMenuListener() {
            public void poppingUp(Object object, JPopupMenu popup) {
                TranscriptWindow chatWindow = (TranscriptWindow)object;
                Action clearAction = new AbstractAction() {
                    public void actionPerformed(ActionEvent actionEvent) {
                        try {
                            chatWindow.insert("My own text :)");
                        }
                        catch (BadLocationException e) {
                            Log.error(e);
                        }
                    }
                };

                clearAction.putValue(Action.NAME, "Insert my own text");
                popup.add(clearAction);
            }

            public void poppingDown(JPopupMenu popup) {

            }

            public boolean handleDefaultAction(MouseEvent e) {
                return false;
            }
        };

        // Add a ChatRoomListener to the ChatManager to allow for notifications
        // when a room is being opened.
        chatManager.addChatRoomListener(new ChatRoomListener() {
            public void chatRoomOpened(ChatRoom room) {
                room.getTranscriptWindow().addContextMenuListener(listener);
            }

            public void chatRoomLeft(ChatRoom room) {
                room.getTranscriptWindow().removeContextMenuListener(listener);
            }
        });
    }

    /**
     * Adds a new menu and child menu item to Spark.
     */
    private void addMenuToSpark(){
        // Retrieve the MainWindow UI from Spark.
        MainWindow mainWindow = SparkManager.getMainWindow();
        // Create new Menu
        JMenu myPluginMenu = new JMenu("My Plugin Menu");
        // Create Action to test Menu install.
        Action showMessage = new AbstractAction() {
            public void actionPerformed(ActionEvent actionEvent) {
                JOptionPane.showMessageDialog(mainWindow, "Yeah, It works.");
            }
        };

        // Give the menu item a name.
        showMessage.putValue(Action.NAME, "Check if it works");

        // Add to Menu
        myPluginMenu.add(showMessage);

        // Add Menu To Spark
        mainWindow.getJMenuBar().add(myPluginMenu);
    }

    /**
     * Adds a button to each Chat Room that is opened.
     */
    private void addChatRoomButton(){
        // Retrieve ChatManager from the SparkManager
        ChatManager chatManager = SparkManager.getChatManager();

        // Create a new ChatRoomButton.
        ChatRoomButton button = new ChatRoomButton("Push Me");


        // Add to a new ChatRoom when the ChatRoom opens.
        chatManager.addChatRoomListener(new ChatRoomListener() {
            public void chatRoomOpened(ChatRoom room) {
                room.getToolBar().addChatRoomButton(button);
            }

            public void chatRoomLeft(ChatRoom room) {
                room.getToolBar().removeChatRoomButton(button);
            }
        });
    }

    /**
     * Called after Spark is loaded to initialize the new plugin.
     */
    public void initialize() {
        // Register new Searchable object "SearchMe" with the SearchManager.
        SearchManager searchManager = SparkManager.getSearchManager();
        searchManager.addSearchService(new SearchMe());
    } 

 
package org.jivesoftware.spark.plugin.example;

import org.jivesoftware.spark.search.Searchable;
import org.jivesoftware.spark.SparkManager;
import org.jivesoftware.resource.LaRes;

import javax.swing.Icon;
import javax.swing.JOptionPane;

/**
 * A simple example of how to integrate ones own search into Spark.
 */
public class SearchMe implements Searchable {

    /**
     * The icon to show in the search box.
     * @return the icon.
     */
    public Icon getIcon() {
        return LaRes.getImageIcon(LaRes.SMALL_AGENT_IMAGE);
    }

    /**
     * Returns the name of this search object that is displayed in the drop down box.
     * @return the name.
     */
    public String getName() {
        return "Searches Nothing Really";
    }

    /**
     * Returns the text that should be displayed in grey when this searchable object
     * is initially selected.
     * @return the text.
     */
    public String getDefaultText() {
        return "Click to search me.";
    }

    /**
     * Returns the text to display in the tooltip.
     * @return the tooltip text.
     */
    public String getToolTip() {
        return "Shows an example of integrating ones own search into Spark.";
    }

    /**
     * Is called when a user hits "Enter" key.
     * @param query the query the user is searching for.
     */
    public void search(String query) {
        JOptionPane.showMessageDialog(SparkManager.getMainWindow(), "Nothing Found :(");
    }
}

    /**
     * Listen for incoming transfer requests and either handle them yourself, or pass them
     * off to be handled by the next listener. If no one handles it, then Spark will handle it.
     */
    private void addTransferListener(){
        SparkTransferManager transferManager = SparkManager.getTransferManager();

        transferManager.addTransferListener(new TransferListener() {
            public boolean handleTransfer(FileTransferRequest request) {
                // If I wanted to handle it, take the request, accept it and get the inputstream.
                
                // Otherwise, return false.
                return false;
            }
        });
    }

    /**
     * Sends a file to a user in your ContactList.
     */
    private void sendFile(){
        // Retrieve SparkTransferManager from the SparkManager.
        SparkTransferManager transferManager = SparkManager.getTransferManager();

        // In order to send a file to a person, you will need to know their full Jabber
        // ID.

        // Retrieve the Jabber ID for a user via the UserManager. This can
        // return null if the user is not in the ContactList or is offline.
        UserManager userManager = SparkManager.getUserManager();
        String jid = userManager.getJIDFromNickname("Matt");
        if(jid != null){
            transferManager.sendFile(new File("MyFile.txt"), jid);
        }
    }

    /**
     * Controls the UI of a ContactItem.
     */
    private void handleUIAndEventsOfContactItem(){
        ContactList contactList = SparkManager.getWorkspace().getContactList();
        ContactItem item = contactList.getContactItemByJID("paul@jivesoftware.com/spark");
        ContactItemHandler handler = new ContactItemHandler() {
            /**
             * Called when this users presence changes. You are responsible for changing the
             * icon (or not) of this contact item.
             * @param presence the users new presence.
             */
            public void handlePresence(Presence presence) {

            }

            /**
             * Is called when a user double-clicks the item.
             * @return true if you are handling the event.
             */
            public boolean handleDoubleClick() {
                return false;
            }
        };

        item.setHandler(handler);
    }

    /**
     * Allows a plugin to be notified when the Spark users changes their
     * presence.
     */
    private void addPersonalPresenceListener(){
        SessionManager sessionManager = SparkManager.getSessionManager();

        sessionManager.addPresenceListener(new PresenceListener() {

            /**
             * Spark user changed their presence.
             * @param presence the new presence.
             */
            public void presenceChanged(Presence presence) {
                
            }
        });
    }

    /**
     * Installs a new MessageFilter.
     */
    private void installMessageFilter() {
        // Retrieve the ChatManager from SparkManager
        ChatManager chatManager = SparkManager.getChatManager();

        MessageFilter messageFilter = new MessageFilter() {
            public void filter(Message message) {
                String currentBody = message.getBody();
                currentBody = currentBody.replaceAll("bad words", "good words");
                message.setBody(currentBody);
            }
        };

        chatManager.addMessageFilter(messageFilter);
        // Just remember to remove your filter if need be.
    }

    /**
     * Creates a person to person Chat Room and makes it the active chat.
     */
    private void createPersonToPersonChatRoom(){
        // Get the ChatManager from Sparkmanager
        ChatManager chatManager = SparkManager.getChatManager();
        // Create the room.
        ChatRoom chatRoom = chatManager.createChatRoom("don@jivesoftware.com", "Don The Man", "The Chat Title");
        // If you wish to make this the active chat room.
        // Get the ChatContainer (This is the container for all Chat Rooms)
        ChatContainer chatContainer = chatManager.getChatContainer();
        // Ask the ChatContainer to make this chat the active chat.
        chatContainer.activateChatRoom(chatRoom);
    }

    /**
     * Creates a person to person Chat Room and makes it the active chat.
     */
    private void createConferenceRoom() {
        // Get the ChatManager from Sparkmanager
        ChatManager chatManager = SparkManager.getChatManager();
        Collection serviceNames = null;
        // Get the service name you wish to use.
        try {
            MultiUserChatManager multiUserChatManager = MultiUserChatManager.getInstanceFor( SparkManager.getConnection() );
            serviceNames = multiUserChatManager.getServiceNames();
        }
        catch (Exception e) {
            Log.error(e);
        }

        // Create the room.
        ChatRoom chatRoom = chatManager.createConferenceRoom("BusinessChat", (String)serviceNames.toArray()[0]);

        // If you wish to make this the active chat room.
        // Get the ChatContainer (This is the container for all Chat Rooms)
        ChatContainer chatContainer = chatManager.getChatContainer();
        // Ask the ChatContainer to make this chat the active chat.
        chatContainer.activateChatRoom(chatRoom);
    }
}

• Create a class that implements Preference.

  package org.jivesoftware.spark.plugin.example.preferences;
  
  import org.jivesoftware.spark.preference.Preference;
  import org.jivesoftware.resource.LaRes;
  
  import javax.swing.Icon;
  import javax.swing.JComponent;
  
  public class MyPreferences implements Preference {
  
      private MyPreferenceUI ui;
  
      public MyPreferences(){
          ui = new MyPreferenceUI();
      }
  
  
      public String getTitle() {
          return "Example Preferences";
      }
  
      public Icon getIcon() {
          return LaRes.getImageIcon(LaRes.ADD_IMAGE_24x24);
      }
  
      public String getTooltip() {
          return "Example tooltip in preference dialog";
      }
  
      public String getListName() {
          return "Examples";
      }
  
      public String getNamespace() {
          return "EXAMPLE";
      }
  
      public JComponent getGUI() {
          return ui;
      }
  
      public void load() {
          // Would load persisted information from file or server and
          // set the UI appropriately.
          ui.setShowChatHistory(true);
      }
  
      public void commit() {
          // Would persist the current state of the preferences.
          boolean showChatHistory = ui.isChatHistoryShown();
  
      }
  
      public boolean isDataValid() {
          return true;
      }
  
      public String getErrorMessage() {
          return null;
      }
  
      public Object getData() {
          return null;
      }
  
      public void shutdown() {
          // Do nothing.
      }
  }
  
  

• Create a UI class that your Preference will use.

  package org.jivesoftware.spark.plugin.example.preferences;
  
  import org.jivesoftware.spark.util.ResourceUtils;
  
  import javax.swing.JCheckBox;
  import javax.swing.JPanel;
  
  import java.awt.FlowLayout;
  
  /**
   * Demonstrates a simple panel used to display a UI that can be used as
   * the Preference UI in the Preferences Dialog. This panel shows a simple
   * UI with accessors for setting the preference values / persistence.
   */
  public class MyPreferenceUI extends JPanel {
  
      private JCheckBox showChatHistory;
  
      /**
       * Creates the default panel using FlowLayout as the Layout. But
       * GridBagLayout is the really only true layout :)
       */
      public MyPreferenceUI() {
          setLayout(new FlowLayout(FlowLayout.LEFT));
          buildUI();
      }
  
      private void buildUI() {
          showChatHistory = new JCheckBox();
          // Use Mnemonics for the CheckBox using ResourceUtils.
          ResourceUtils.resButton(showChatHistory, "&Show Chat History in Chat Window");
          // Add Button
          add(showChatHistory);
      }
  
      /**
       * Sets the UI based on previous preferences.
       * @param show true if Chat History to show up.
       */
      public void setShowChatHistory(boolean show){
          showChatHistory.setSelected(show);
      }
  
      /**
       * Returns true if Chat History should be shown.
       * @return true if history shown.
       */
      public boolean isChatHistoryShown(){
          return showChatHistory.isSelected();
      }
  
  }
  

• Register the Preference class with Preference Manager in your plugin's initialize() method.

      public void initialize() {
          PreferenceManager preferenceManager = SparkManager.getPreferenceManager();
          preferenceManager.addPreference(new MyPreferences());
      }
  

    // Get the ChatContainer from the ChatManager.
    ChatManager chatManager = SparkManager.getChatManager();
    ChatContainer chatContainer = chatManager.getChatContainer();
    // Get the room you wish to be notified.
    ChatRoom chatRoom = chatContainer.getActiveChatRoom();
    chatContainer.startFlashing(chatRoom);