Spark 帮助文档(官方也有)

1、Overview of the Spark ClientThe Spark client is designed with the idea that most users find the different aspects of a chat client familiar and easy to use. All components you see below are either accessible from the Workspace or ChatRoom object and can be manipulated based on your needs.Overview of

2、 the Spark APIThe Spark API provides a framework for adding extensions on top of the protocol and/or UI of the Spark client. For example, you could write your own message filter or add a button to a chat room and send files using the File Transfer API. The Spark API has the following characteristics

3、: Several event listeners to either intercept, be informed of, or execute custom code in response to a particular IM event. Thorough tie-ins to the UI to allow for customization from simple icon changes, to adding buttons, to adding your own menu items. Ability to add your own XMPP functions using t

4、he SMACK API. Managers - Managers allow for better (lazy) loading of particular areas within the Spark client as well as providing access points to the system. Some of the more relevant managers are: o SparkManager - Acts as the central manager for all of Spark. You use this manager to get instances

5、 of ChatManager, SessionManager, SoundManager, and UserManager. o ChatManager - Handles registration of most chat listeners and filters, as well as creation and retrieval of chat rooms. It is also used to retrieve the UI of the ChatFrame. o SessionManager - Contains the information about the current

6、 session, such as the server connected to, the handling of connection errors and notification of personal presence changes. o SoundManager - Used to play sounds. Event Handlers - Spark contains numerous listeners and handlers to allow more pluggability into the Spark client. Some of the more common

7、listeners and handlers are: o ChatRoomListener (and ChatRoomListenerAdapter) - Allows the plugin to listen for chat rooms being opened, closed and activated. You would generally use this to customize individual chat rooms. o MessageListener - Allows for notification when a message has been received

8、or sent. o ContactGroupListener - Allows for notification of changes to a Contact Group. o ContactListListener - Allows for notification of changes to the Contact List. o TransferListener - Allows you to intercept File transfers. o ContextMenuListener - Allows for the addition or removal of actions

9、or menu items to right-click (context menu) popups. o PresenceListener - Allows for notification when Spark presence changes. o ContactItemHandler - Allows the plugin to control the effects of presence changes within a ContactItem and the associated invoke call. Components - Spark contains many Swin

10、g components that will regularly be used during the creation of your plugin. Some of the more commonly used components are : o MainWindow - The frame containing the Contact List. You use MainWindow to add new tabs, menu items, or force focus. o ChatRoom - The base abstract class of all chat rooms wi

11、thin Spark. Known implementations are ChatRoomImpl and GroupChatRoom. o ChatArea - The base chat viewer for both the TranscriptWindow and ChatInputEditor. o ContactList - The ContactList UI in Spark. o ChatRoomButton - The button that should be used to conform to the look and feel of other buttons w

12、ithin a ChatRoom. Structure of a PluginPlugins are shipped as compressed JAR (Java Archive) files. The files in a plugin archive are as follows:Plugin Structuremyplugin.jar!/ |- plugin.xml - Plugin definition file |- libs/ - Contains all the class archives needed to run this plugin.The plugin.xml fi

13、le specifies the main Plugin class. A sample file might look like the following:Sample plugin.xml Google Desktop Plugin com.examples.plugins.GooglePlugin Derek DeMoro 1.0 Enables users to find files and emails relating to users using Google Desktop technology. Installing your P

14、luginYou only need to drop your newly created jar file into the plugins directory of your Spark client install.Directory StructureSpark/ |- plugins/ - Put your Sparkplug jar file here |- lib/ - The main classes and libraries needed to run Live Assistant |- resources/ - Contains other supportive docu

15、ments and libraries |- docs/ - Help Manuals and the JavaDoc to help you develop your own plugins.Your plugin class must implement the Plugin interface from the Spark Client API. The Plugin interface has methods for initializing and shutting down the plugin.Getting Started Writing SparkplugsIn order

16、to build your own Sparkplugs, you will need to setup your project properly to have all items in your classpath. With the Sparkplug.zip or Sparplug.tar.gz you have just extracted, you should see the following contents:Directory StructureSparkplugs/ |- build/ - Simple structure to allow you to easily

17、build your plugins using ANT. |- images/ - Images used in this guide. |- plugin_development_guide.html/ - The complete development guide (this document). |- api/ - Contains the Sparkplug Javadocs. |- spark/ - The spark build structure you will need for classpath purposes |-bin - Contacts the startup

18、.bat which starts up Spark for testing. |-lib - Contains all the archives needed to run Spark. |-logs - Where all logs are stored. |-plugins - Location where all plugins should be deployed to. |-resources - Contains native libraries for running OS specific operations.To setup a project to run Spark

19、within your IDE, you will need to the following: It is required that you use the 1.4 JRE to build Spark. Add all *.jar files in the Sparkplugs/spark/lib and Sparkplugs/spark/lib/windows directories to your classpath. Add the resource directory (Sparkplugins/spark/resource) to your classpath for the

20、native libraries. Main Class - com.jivesoftware.Spark VM Parameters - -Dplugin=path_to_your_plugin.xml file. This allows you to run your plugins within your IDE without deploying. Thats it. We have also provided a build structure to easily build and deploy your own plugins directly into your Spark t

21、est bed. To use, read the how-to-build.txt file in the builder/ directory.Spark How-TosAll code samples can be found in the examples.jar file located here. How do I create a simple plugin? How do I add my own Tab to the Spark Workspace? How do I add a context menu listener to the contact list? How d

22、o I add my own ContextMenu Listener to a ChatRoom? How do I add my own Menu to Spark? How do I add a button to a Chat Room? How do I add my own searching feature in Spark like the User Search or Google Search in Firefox? How can I intercept a File Transfer request? How can I send a file to another u

23、ser? How can I control the UI and event handling of a ContactItem? How can I be notified when the Spark user changes their presence? How can I add a message filter? How can I create a person-to-person Chat Room? How can I create a public Conference room? How can I add my own Preferences? How can I f

24、lash the chat frame, like when a new message comes in? How do I create a simple plugin?1. Implement Plugin. Simple Pluginpackage com.jivesoftware.spark.examples;import com.jivesoftware.spark.plugin.Plugin;/* * Implements the Spark Plugin framework to display the different possibilities using * Spark

25、. */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 vo

26、id 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 resour

27、ces and * remove any components install in Spark. */ public void uninstall() / Remove all resources belonging to this plugin. How to add your own Tab to the Spark Workspace?1. Implement Plugin. 2. Retrieve the Workspace which is the UI for Spark. 3. Retrieve the WorkspacePane which is the Tabbed Pan

28、e used by Spark. 4. Add your own tab. Add a Tab to Sparkpublic 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. JTa

29、bbedPane tabbedPane = workspace.getWorkspacePane(); / Add own Tab. tabbedPane.addTab(My Plugin, new JButton(Hello); .How do I add a context menu listener to the contact list?1. Implement Plugin. 2. Retrieve the ContactList which is part of Sparks Workspace. 3. Add ContactListListener. Add a ContextM

30、enu Listener to ContactListprivate 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 f

31、inal 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 Context

32、MenuListener() 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; ); How do I add my own ContextMenu Listener to a ChatRoom1. Impl

33、ement Plugin. 2. Add a ChatRoomListener to the ChatManager. 3. Get either the TranscriptWindow or ChatInputEditor from the ChatRoom. 4. Add a ContactMenuListener to the ChatArea. Add a ContextMenuListener to a ChatRoom, TranscriptWindow or ChatInputEditorprivate void addContactListenerToChatRoom() /

34、 Retrieve a ChatManager from SparkManager ChatManager chatManager = SparkManager.getChatManager(); final ContextMenuListener listener = new ContextMenuListener() public void poppingUp(Object object, JPopupMenu popup) final TranscriptWindow chatWindow = (TranscriptWindow)object; Action clearAction =

35、new AbstractAction() public void actionPerformed(ActionEvent actionEvent) try chatWindow.insert(My own text :); catch (BadLocationException e) e.printStackTrace(); ; clearAction.putValue(Action.NAME, Insert my own text); popup.add(clearAction); public void poppingDown(JPopupMenu popup) public boolea

36、n handleDefaultAction(MouseEvent e) return false; ; / Add a ChatRoomListener to the ChatManager to allow for notifications / when a room is being opened. Note: I will use a ChatRoomListenerAdapter for brevity. chatManager.addChatRoomListener(new ChatRoomListenerAdapter() public void chatRoomOpened(C

37、hatRoom room) room.getTranscriptWindow().addContextMenuListener(listener); public void chatRoomLeft(ChatRoom room) room.getTranscriptWindow().removeContextMenuListener(listener); ); How do I add my own Menu to Spark?1. Implement Plugin. 2. Retrieve the MainWindow from SparkManager. 3. Either create

38、a new Menu or add a MenuItem to one of the pre-existing menus. Add a Menu To Spark/* * Adds a new menu and child menu item to Spark. */ private void addMenuToSpark() / Retrieve the MainWindow UI from Spark. final MainWindow mainWindow = SparkManager.getMainWindow(); / Create new Menu JMenu myPluginM

39、enu = 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

40、it works); / Add to Menu myPluginMenu.add(showMessage); / Add Menu To Spark mainWindow.getJMenuBar().add(myPluginMenu); How do I add a button to a Chat Room?1. Implement Plugin. 2. Add a ChatRoomListener to ChatManager. 3. When the room is opened, add your ChatRoomButton to the ToolBar of the ChatRo

41、om. Add a button to a Chat Room/* * 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. final ChatRoomButton button = new ChatRoomButto

42、n(Push Me); / Add to a new ChatRoom when the ChatRoom opens. chatManager.addChatRoomListener(new ChatRoomListenerAdapter() public void chatRoomOpened(ChatRoom room) room.getToolBar().addChatRoomButton(button); public void chatRoomLeft(ChatRoom room) room.getToolBar().removeChatRoomButton(button); );

43、 How do I add my own searching feature in Spark like the User Search or Google Search in Firefox?1. Implement Plugin. 2. Create a searchable object by implementing the Searchable interface. 3. Add the Searchable implementation to the SearchManager. Add a search feature to Spark like User Search or G

44、oogle Search in Firefox/* * 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(); See the S

45、earchMe code below. package com.jivesoftware.spark.examples;import com.jivesoftware.spark.search.Searchable;import com.jivesoftware.spark.SparkManager;import com.jivesoftware.resource.LaRes;import javax.swing.Icon;import javax.swing.JOptionPane;/* * A simple example of how to integrate ones own sear

46、ch 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.

47、 */ 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. *

48、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.getM

49、ainWindow(), Nothing Found :(); How can I intercept a File Transfer request?1. Implement Plugin. 2. Implement TransferListener. 3. Register your TransferListener. Intercept File Transfer Requests/* * Listen for incoming transfer requests and either handle them yourself, or pass them * off to be hand

50、led 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 i