Connect. Communicate. Collaborate PerfsonarUI plug-in tutorial Nina Jeliazkova BREN, Bulgaria

Connect. Communicate. Collaborate Roadmap Objective –teach developers how to create a visualisation for perfsonar web services and make it as easy as possible for them to start developing perfsonarUI plug-ins Content –This presentation organized as FAQ Q. How to... ? A..... –Most important code snippets from my point of view based on the questions asked by plugin developers –DemoPlugin

Connect. Communicate. Collaborate Where to find PerfsonarUI Releases at perfSONAR wiki – Java Web start – Source code at perfSONAR SVN repository – –Javadoc Whom to contact

Connect. Communicate. Collaborate Q.What is perfsonarUI plug-in PerfsonarUI plug-in I are jar file, found in PerfsonarUI-vX.XX/bin/ext folder. Plugins are loaded on startup: –Each jar in that folder is scanned to find a class, implementing IPerfsonarTab interface. IPerfsonarTab –All found IPerfsonarTab classes are instantiated, added to PerfsonarTabsList and sorted by their IPerfsonarTab.getOrder() property.IPerfsonarTab PerfsonarTabsListIPerfsonarTab.getOrder() –Command line parameters are set to each tab via IPerfsonarTab.setParameters(java.l ang.String[]) IPerfsonarTab.setParameters(java.l ang.String[]) –For each IPerfsonarTab a PerfsonarTaskPane is created and added as a new tab.IPerfsonarTab PerfsonarTaskPane org.perfsonar.perfsonarui.PerfsonarTab

Connect. Communicate. Collaborate Q.How to create perfsonarUI plug-in Create a class that implements org.perfsonar.perfsonarui.plugin s.IPerfsonarTab The default implementation is org.perfsonar.perfsonarui.Perfso narModel toString() – the tab title getOrder() - the tab position createMainComponent() – the tab user interface

Connect. Communicate. Collaborate Q.How to create perfsonarUI main panel Create a class that descends from org.perfsonar.perfsonarui.ui.PluginMainPanel The plug-in (i.e. IPerfsonarTab object) is passed as a constructor parameter The component appears at right side in each tab.

Connect. Communicate. Collaborate Q. How to create menus on the left side of the tab? For each item in IPerfsonarTab.getActions() a link on the left is created.IPerfsonarTab.getActions() PSActionMap getActions() is an javax.swing.ActionMap of PSUIActionPSActionMapgetActions The default PerfsonarModel creates new PSActionMap and adds actions created by following methods: –createEndpointsAction –createOptionsAction –createDataRequestAction –createMetadataRequestAction –createClearAction

Connect. Communicate. Collaborate Q. How to change default actions? Override any of these methods in your implementation of IPerfsonarTab –createEndpointsAction –createOptionsAction –createDataRequestAction –createMetadataRequestAction –createClearAction Actions IPerfsonarTab.getActions() are an PSActionMap of PSUIAction descendants. You may find useful following actions:IPerfsonarTab.getActions()PSActionMapPSUIAction –PerfsonarRequestAction descendants – to send requests.PerfsonarRequestAction –SetOptionsAction displays IPerfsonarTab.createOptionsComponent(java.awt.Component) in a JTabbedPane.SetOptionsAction IPerfsonarTab.createOptionsComponent(java.awt.Component) –EndpointsAction Perfsorm some action on a list of services (e.g. select, check status).EndpointsAction –ClearAction Calls IPerfsonarTab.clear().ClearActionIPerfsonarTab.clear()

Connect. Communicate. Collaborate Q. How to add more actions? Create new PSUIAction and add it to the ActionMap, obtained via getActions(). – myAction = createMyAction(); –getActions.put(myAction.getValue(Action.NAME),myAction); –myAction.setActions(getActions());

Connect. Communicate. Collaborate Q. Why new type PSAction is introduced, instead of javax.swing.Action ? Some new fields added: –voidenableActions(boolean enable)enableActions –java.awt.ComponentgetFrame()getFrame –java.lang.StringgetGroup()getGroup –intgetOrderInGroup()getOrderInGroup –voidsetActions(PSActionMap actions)setActionsPSActionMap –voidsetFrame(java.awt.Component frame)setFrame –voidsetGroup(java.lang.String group)setGroup –voidsetOrderInGroup(int orderInGroup)setOrderInGroup

Connect. Communicate. Collaborate Q. How actions are grouped and how to change/create new groups? Use PSUIAction.setGroup(String) to assign group title to an action PSUIActions with the same group name are displayed in a box on the left, the title is group name Default group names defined in IPerfsonarTab: –public static String defaultGroupQueryOption = "Query options"; –public static String defaultGroupQuery = "Execute query"; –public static String defaultGroupHidden = "HIDDEN";

Connect. Communicate. Collaborate Q. How to not include an action in the left panel? Use myAction.setGroup(IPerfsonarGroup.defaultGroupHidden)

Connect. Communicate. Collaborate Q. How to add an arbitrary component n the left? In your IPerfsonarTab descendant, override –javax.swing.JComponent[] createDetailsComponent(java. awt.Component parentCompon ent) createDetailsComponent If not null, all JComponents will be displayed at the left pane, just below the actions.

Connect. Communicate. Collaborate Summary A set of clickable actions on the left. Actions are created by IPerfsonarTab.getActions(). IPerfsonarTab.getActions() Set of panels ( JComponent[ ] ) displaying some details of the query or the result just below actions. Created by IPerfsonarTab.createDetailsComponent IPerfsonarTab.createDetailsComponent Status bar, which is configured as a listener to IPerfsonarTab#.getRequest IPerfsonarTab#.getRequest Main panel ( PluginMainPanel ) PluginMainPanel Created by IPerfsonarTab. IPerfsonarTab. createMainComponent()

Connect. Communicate. Collaborate Q. How to I change/add options menu? In your IPerfsonarTab descendant, override – javax.swing.JComponent[]crea teOptionsComponent(java.awt.Component parentComponent)crea teOptionsComponent If not null will be displayed in a tabbed window by SetOptionsAction, each JComponent in a different tab. SetOptionsAction

Connect. Communicate. Collaborate Q. Where the list of service addresses comes from? “Service addresses” menu is by default: –An org.perfsonar.perfsonarui.ui.actions.ShowEndpointsAction –Created by IPerfsonarTab.createEndpointsAction() Display the content of MAEndpointListMAEndpointList –org.perfsonar.perfsonarui.plugins.MAEndpointList - a list of MAEndpoint.MAEndpointList MAEndpoint Available in IPerfsonarTab: –MAEndpointList getEndpointList()MAEndpointListgetEndpointList –voidsetEndpointList(MAEndpointList endpointList)setEndpointListMAEndpointList

Connect. Communicate. Collaborate Q. How service addresses list is initialized? Initialized in IPerfsonarTab: 1.Either MAEndpointsList is passed as constructor parameter, or 2.The list is created by public MAEndpointList createEndpoints() { return new MAEndpointList(getMAconf("MA.conf"),getSupportedRequests()); } 3.If command line option -e,--endpoints, URL for MA.conf, default then the list is read from the url by endpointList.readEndpoints(new URL(url)); –Fall back mechanism: If not available, retrieves the internal copy of MA.conf, packed in the jar

Connect. Communicate. Collaborate Q. How to obtain the selected service addresses? Use methods from IPerfsonarTab: –To get endpoints: MAEndpointListMAEndpointList getEndpointList()getEndpointList –To find selected endpoints: MAEndpointListMAEndpointList getEndpointList()getEndpointList for (int i=0; i < endpoints.size();i++) { MAEndpoint mae = endpoints.get(i); if (mae.isEnabled()) { //this endpoint has been selected //e.g. send a request } –Two flavours of MAEndpointList : booleanisMultipleEndpoints() If false, only one endpoint at time can be enabled, otherwise, arbitrary number of endpoints can be enabled.isMultipleEndpoints voidsetMultipleEndpoints(boolean multipleEndpoints)setMultipleEndpoints

Connect. Communicate. Collaborate Q. How to show the selected endpoints in main panel ? Example: –Initialize MAEndpointList to allow only one selected endpoint at timeMAEndpointList –Create text field for the URL urlField = new JFormattedTextField(data.getEndpoint().getEndpoint()); –MAEndpointList is an Observable. Add the PluginMainPanel descendant as ObserverMAEndpointList public class PlaygroundPanel extends PluginMainPanel implements Observer,…. { … getEndpointsList().addObserver(this) } –Listen for changes public void update(Observable arg0, Object arg1) { if (arg0 instanceof MAEndpointsList) { //get the selected endpoint and update the text field urlField.setText(…); } Similar example in PlaygroundPanel

Connect. Communicate. Collaborate Q.How to display selected endpoint ? Example: –Initialize MAEndpointList to allow only one selected endpoint at timeMAEndpointList –Create text field for the URL urlField = new JFormattedTextField(data.getEndpoint().getEndpoint()); –MAEndpointList is an Observable. Add the PluginMainPanel descendant as ObserverMAEndpointList public class PlaygroundPanel extends PluginMainPanel implements Observer,…. { … getEndpointsList().addObserver(this) } –Listen for changes public void update(Observable arg0, Object arg1) { if (arg0 instanceof MAEndpointsList) { //get the selected endpoint and update the text field urlField.setText(…); } Similar example in PlaygroundPanel

Connect. Communicate. Collaborate Summary org.perfsonar.perfsonarui.IPerfso narTaborg.perfsonar.perfsonarui.IPerfso narTab a placeholder for several common data structures, that are deemed sufficient to create and send a request and process the response of perfSONAR service: MAEndpointList contains the list of services (addresses and other info as in MAEndpoint, that will be used in this IPerfsonarTab. Note that each tab may support its own list of services. This is accessible via IPerfsonarTab.getEndpointList(), IPerfsonarTab.setEndpointList()MAEndpointListMAEndpoint IPerfsonarTab IPerfsonarTab.getEndpointList() IPerfsonarTab.setEndpointList() IUserData MetaDataList SmartMARequest MAEndpointList

Connect. Communicate. Collaborate MAEndpoint - Lesson1-1 Lessons and demo plugin code used in the presentation are available in SVN repository org.perfsonar.perfsonarui.demo.Lesson1 MAEndpoint encapsulates information about perfsonar service (address, name,schema) Currently list of addresses are read from a configuration file MA.conf The intention is to populate the same data structure with information retrieved from LS Latest configuration file used by JWS PerfsonarUI is at

Connect. Communicate. Collaborate MAEndpointList: Lesson1-2 MAEndpointList class –org.perfsonar.perfsonarui.plugins package –Encapsulates Vector –Extends Observable –Methods to read configuration file and filter services based on schema Example code in lessons: –task2() - retrieve all services listed in –task3() - retrieve all BWCTL services listed in Future development: –populate MAEndpointList from Lookup Service

Connect. Communicate. Collaborate Q. What “Query” menu in Demo plug-in does? Sends SetupDataRequest, customized by fields of IPerfsonarTab object, available by IUserData getUserData() Holds query and response data for a single entity (e.g. an interface).IUserDatagetUserData voidsetUserData(IUserData use rData) Sets the query.setUserDataIUserData

Connect. Communicate. Collaborate Q. What IUserData field is for? IUserData holds query and response data for a single entity (e.g. an interface in MA service, pair in IPPM service).IUserData Accessible via –IPerfsonarTab.getUserData()IPerfsonarTab.getUserData() –IPerfsonarTab.setUserData()IPerfsonarTab.setUserData() In PerfsonarModel descendants is created by createData()createData() –Example (demo public IUserData createUserData() { return new UserData(true); }

Connect. Communicate. Collaborate Interface IUserData Purpose –Placeholder for query and response data necessary to communicate with Perfsonar service Package –org.perfsonar.perfsonarui.plugins Most important methods: –setEndpoint(MAEndpoint endpoint) ; –String getQuery(String name) –setQuery(String name, String value); –setResponse(String name, String value); –String getResponse(String name); Default implementation: –AbstractUserData : two hash tables – one for query values and one for response values –Advantages : generic structure, not fixed to particular schema –Disadvantages: Some concerns about type safety Lesson2-1

Connect. Communicate. Collaborate AbstractUserData package –org.perfsonar.perfsonarui Default IUserData implementation: –two hash tables – one for query values and one for response values –extends Observable –user interface classes can register as Observers and reflect its changes (e.g. UserDataPanel) Lesson2-2

Connect. Communicate. Collaborate Q. How to change IUserData query fields? User interaction : –In PluginMainPanel descendant: Create JComponent that displays/allows to edit IPerfsonarTab.getUserData() query fields.IPerfsonarTab.getUserData() QueryDetailsPanel used as example in DemoPlugin Similar implementation in Circuits tab Programmatically –Create PerfsonarRequestAction descendant (in IPerfsonarTab class) and pass IPerfsonarTab.getUserData as a parameter: public PerfsonarRequestAction createDataRequestAction() { return new SetupDataRequestAction(request,userData,responseData, "Query",null,defaultGroupQuery) { public void prepareQuery(IUserData userData) { userData.setTime(startTime - timeInterval, timeInterval); //force retrieval of data for both directions userData.setQuery(UserData.C_DIRECTION,AbstractUserData.NULL_DATA); }; }

Connect. Communicate. Collaborate Q. OK, how to send a request based on IUserData query fields? In IPerfsonarTab descendant, –Override createSMARTRequest() to create AbstractMARequest descendant based on endpoints details –Customize your request class by implementing public org.w3c.dom.Document createRequest(IUserData uData, String messageType) –Create an action, that calls request.makeRequest(IUserData) –Or use/derive from existing classes E.g. SetupDataRequestAction, MetadataRequestAction

Connect. Communicate. Collaborate SMARTMARequest Package org.perfsonar.perfsonarui An implementation of IPerfsonarRequest that understands different schema versions, based on the endpoint MAEndpoint. The descendants should implement createMARequest(MAEndpoint) and create specific IPerfsonarRequest based on MAEndpoint.getSchema()IPerfsonarRequestMAEndpointcreateMARequest(MAEndpoint)IPerfsonarRequestMAEndpoint.getSchema() Send request to different MA Query aggregation Sending requests in parallel threads Lesson3-1

Connect. Communicate. Collaborate SmartMARequest Lesson 3-1 : makeRequest(IUserData uData, String messageType, IPerfsonarResponse response, boolean runInThread) MetadatakeyRequest with parameters specified by IUserData 1)Query GEANT2 RRD MA for specific IP, then query ISTF RRD MA for all available interfaces. 2)The result is available in MetadataList object

Connect. Communicate. Collaborate SmartMARequest Lesson 4-1 : Send SetupDataRequest with parameters specified by IUserData Lesson 4-1 : Send SetupDataRequest with parameters specified by MetadataList. It may consist of IUserData with different endpoints. SMARTMARequest will send separate queries.

Connect. Communicate. Collaborate AbstractMARequest Default implementation of IPerfsonarRequest Sends requests synchronously or asynchronously Abstract methods, have to be implemented by descendant classes:

Connect. Communicate. Collaborate Q.How to implement classes to handle new request types Implement interface IPerfsonarRequest or subclass AbstractMARequest Most important IPerfsonarRequest methods:

Connect. Communicate. Collaborate Q. Where is the response message? The response received on voidmakeRequest(IUserData uData, java.lang.String messageType, IPerfsonarResponse response, boolean runInThread)makeRequestIUserData IPerfsonarResponse is passed to a response listener IPerfsonarResponse IPerfsonarResponse Several response listeners available:

Connect. Communicate. Collaborate Summary IPerfsonarResponse An interface to be implemented by classes that will receive response from perfSONAR service. This is basically a PropertyChangeListener that listens for PerfsonarResponseEventIPerfsonarResponse PerfsonarResponseEvent All Known Implementing Classes: IUserData MetaDataList SmartMARequest MAEndpointList IPerfsonarResponse

Connect. Communicate. Collaborate Q. What UserDataResponseListener does? Calls IUserData.setResponse() for all fields under nmwgt:interface node atl-cr1.es.net so-4/0/0.0 atl-cr1->elp-cr1:oc48(p2p)::show:intracloud in ESnet-Public –IUserData.setResponse(“ ifAddress ”,” ”); –IUserData.setResponse(“ hostName ”,” atl-cr1.es.net ”);

Connect. Communicate. Collaborate Q. How to display the updated response fields? The default implementation of IUserData (AbstractUserData) is Observable In PluginMainPanel add a component, or the panel itself to be Observer for IperfsonarTab.getUserData() – org.perfsonar.perfsonarui.ui.panels.ResponseDetailsPane is an example of such component Implement update() method in the observer. It is invoked on any change in the IUserData fields

Connect. Communicate. Collaborate Q. How to retrieve utilization data? Create action that calls makeRequest with ITimeValueResponseListener

Connect. Communicate. Collaborate Q. How to retrieve data for more than one interface? In IPerfsonarTab descendant, –Override createSMARTRequest() to create AbstractMARequest descendant based on endpoints details –Customize your request class by implementing public abstract Document createRequest(MAEndpoint endpoint, MetaDataList query, String messageType) throws Exception; –Create an action, that calls AbstractMARequest method public void makeRequest(MAEndpoint endpoint, MetaDataList queryList, String messageType, IPerfsonarResponse response, boolean runInThread) –Or use/derive from existing classes E.g. SetupDataRequestAction, MetadataRequestAction

Connect. Communicate. Collaborate MetadataList Package –org.perfsonar.perfsonarui.plugins Encapsulates ArrayList Extends Observable Used to: –Store information received by MetadataKeyRequest –Specify multiple entries (e.g. interfaces, IPPM pairs) for sending MetadataKeyRequest and SetupDataRequests Lesson2-3. UI for displaying MetadataList and selected item (IUserData) query and response fields

Connect. Communicate. Collaborate Q. What “Retrieve all” menu does? Sends MetadataRequest on selected endpoints Default implementation: –org.perfsonar.perfsonarui.ui.actionsMetadataRequestAction Uses MetadataListListener to fill in IPerfsonarTab.MetadataList MetadataList visualization:

Connect. Communicate. Collaborate Q. How to retrieve time/value data for more than one interface As in previous Q, but use TimeValueResponseListener instead of MetadataListListener Default implementation –SetupDataRefreshActionAll request.makeRequest(null, dataList, IPerfsonarRequest.MA_SetupDataRequest, new TimeValueListResponseListener(dataList), true);

Connect. Communicate. Collaborate Q.Any ready-to use code for NMWG processing? NMWG classes not used so far –Should we reconsider it? org.perfsonar.perfsonarui.NMWGHelper This is a helper class to extract metadata and corresponding data elements from link org.w3c.dom.Document. Process the document and calls void process(Element data, ArrayList metadataChain) for each data item, where metadataChain contains all chained metadata entries for this data. Supports chaining (recent update) NMWGHelper helper = new NMWGHelper() { public abstract void process(Element data, ArrayList metadataChain) throws Exception;{ //do metadata/data processing } };

Connect. Communicate. Collaborate Q.Any ready to use time/value parsing? PSDatum & derived types Value units are inherent part of the object Throws exception if units string is not recognized public void test() { PSUtilizationDatum d = new PSUtilizationDatum(); assertEquals(PSUtilizationDatum.units_bps, d.getType()); d.setBits(1000); assertEquals(1000,d.getBits()); try { d.setValue("1000"); assertEquals(1000,d.getBits()); d.setValue("1000", PSUtilizationDatum.units_Bps); assertEquals(8000,d.getBits()); d.setValue("100", ""); assertEquals(800,d.getBits()); try { d.setValue("100","blabla"); } catch (UnsupportedTypeException xx) { assertEquals("blabla",xx.getMessage()); } } catch (Exception x) { x.printStackTrace(); fail(x.getMessage()); }

Connect. Communicate. Collaborate Q. How to use AA? Under development Derive specific request classes from org.perfsonar.perfsonarui.aa.AAPerfsonarRequest instead of current org.perfsonar.perfsonarui.AbstractMARequest The user have to select an Identity Provider of a list –Examples –urn:geant:edugain:component:be:gidp_federation:dante.net –urn:geant:edugain:component:be:feide:feide.no The user will be asked for a valid username/password

Connect. Communicate. Collaborate The anatomy of the tab org.perfsonar.perfsonarui.IPerfso narTaborg.perfsonar.perfsonarui.IPerfso narTab a placeholder for several common data structures, that are deemed sufficient to create and send a request and process the response of perfSONAR service: MAEndpointList contains the list of services (addresses and other info as in MAEndpoint, that will be used in this IPerfsonarTab. Note that each tab may support its own list of services. This is accessible via IPerfsonarTab.getEndpointList(), IPerfsonarTab.setEndpointList()MAEndpointListMAEndpointIPerfsonarTab IPerfsonarTab.getEndpointList() IPerfsonarTab.setEndpointList() IUserData holds query and response data for a single entity (e.g. an interface in MA service, pair in IPPM service). Accessible via IPerfsonarTab.getUserData(), IPerfsonarTab.setUserData()IUserData IPerfsonarTab.getUserData() IPerfsonarTab.setUserData() MetaDataList is a list of IUserData which should be normally filled in from the response of the MetadataQuery. Accessible via IPerfsonarTab.getDataList(), IPerfsonarTab.setDataList().MetaDataListIUserData IPerfsonarTab.getDataList() IPerfsonarTab.setDataList() SmartMARequest is the class that handles request creation and sending. It can also aggregate requests if configured to do so, send them in parallel or sequentially. Can handle requests that need different XML schema. The request is accessible via IPerfsonarTab.getRequest() and IPerfsonarTab.setRequest().SmartMARequest IPerfsonarTab.getRequest() IPerfsonarTab.setRequest( IUserData MetaDataList SmartMARequest MAEndpointList

Connect. Communicate. Collaborate The anatomy of the tab IUserData MetaDataList SmartMARequest MAEndpointList IPerfsonarResponse

Connect. Communicate. Collaborate Demo plug-in (1) Set to true in order to query > 1 service at time Use only perfsonar 2.0 services Create IUserData instance to be used in all requests Sets the default order of IUserData entries

Connect. Communicate. Collaborate Demo plug-in (2)

Connect. Communicate. Collaborate Demo plug-in (3)

Connect. Communicate. Collaborate Demo plug-in (4) This plug-in will be the last one The main panel The class listening for time/value pairs

Connect. Communicate. Collaborate Demo plug-in (5) Chart view - PerfsonarTimeSeriesDataset Tabular view - ResponseData

Connect. Communicate. Collaborate Demo plug-in (6)

Connect. Communicate. Collaborate Demo plug-in (6)

Connect. Communicate. Collaborate The anatomy of the tab (again) IUserData MetaDataList SmartMARequest MAEndpointList IPerfsonarResponse

Connect. Communicate. Collaborate Summary Create class that implements IPerfsonarTab. The easies way is to extend PerfsonarModel.IPerfsonarTabPerfsonarModel 1.Override PerfsonarModel.createUserData() and instantiate your IUserData class within method (or use the default) 2.Override PerfsonarModel.createDataList and instantiate your MetadataList (sub)class within the method (or use the default) 3.Implement #createSmartRequest 4.Implement #getOrder 5.Create PluginMainPanel descendant that will visualize your data and make #createMainComponent return it.PluginMainPanel 6.If existing IPerfsonarRequest classes are not suitable, derive your own class from AbstractMARequest and make SmartRequest to create it when necessary.IPerfsonarRequestAbstractMARequest 7.Override actions implementations, if necessary.

Connect. Communicate. Collaborate Summary (cont) Decide whether to use current implementations of IUserData and MetadataList or derive your own. If new type of request necessary, subclass AbstractMARequest. –Define new request type new PerfsonarSchema(“MyNewType”) –The “MyNewType” string will be used in MA.conf file –Implement its createRequest() methods, generating request from information available in IUserData (single query) or MetadataList (multiple queries). –Implement processRequest() method

Connect. Communicate. Collaborate Summary (cont) Use existing implementations or implement IPerfsonarResponse Use existing classes for user interface or implement your own and implement PluginMainPanelPluginMainPanel

Connect. Communicate. Collaborate Summary (cont) Use existing implementations or implement IPerfsonarResponse Use existing classes for user interface or implement your own and implement PluginMainPanelPluginMainPanel Use classes from org.perfsonar.perfsonarui.ui.panels package for user interface or implement your own. Most data classes extends Observable and a good approach for UI is to register as Observer and reflect its changes. org.perfsonar.perfsonarui.ui.panels

Connect. Communicate. Collaborate Thank you! Questions?