9.2.3 API with Java

This section describes the setting up of the SOAP framework for Java Standard Edition. Please note that the following instructions expect you to have a working knowledge of Java and the Java development environment. It is also assumed that you already have the Java SDK installed. The example presented in this section has been tested with Java SE Development Kit 7 update 51 and it is recommended to use the same version when trying out the example.

Once you have installed both these additional libraries, consider the example Java code in Listing 2 (the general explanation of this example can be found from Section 9.2.1):

01 import java.util.*; 02 03 class APIExampleApp { 04 public static void main(String[] args) { 05 06 com.metacase.API.MetaEditAPI meServer = null; 07 com.metacase.API.MetaEditAPIPortType port = null; 08 com.metacase.API.METype graphType = new com.metacase.API.METype(); 09 com.metacase.API.MEOop[] graphs = null; 10 com.metacase.API.METype objectType = new com.metacase.API.METype(); 11 com.metacase.API.MEAny[] props = new com.metacase.API.MEAny[1]; 12 com.metacase.API.MEAny[] values = new com.metacase.API.MEAny[1]; 13 com.metacase.API.MEAny area, np; 14 com.metacase.API.MEAny newObjectAny = new com.metacase.API.MEAny(); 15 com.metacase.API.MEOop newObject = new com.metacase.API.MEOop(); 16 com.metacase.API.MEOop[] diagrams = null; 17 com.metacase.API.MEAny place = new com.metacase.API.MEAny(); 18 com.metacase.API.MEAny nullAny = new com.metacase.API.MEAny(); 19 com.metacase.API.MEAny textAny = new com.metacase.API.MEAny(); 20 21 try { 22 meServer = new com.metacase.API.MetaEditAPILocator(); 23 port = meServer.getMetaEditAPIPort(); 24 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 25 26 graphType.setName("WatchFamily"); 27 try { 28 graphs = port.allGoodInstances(graphType); 29 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 30 if(graphs.length == 0) System.exit(2); // No WatchFamily graphs found 31 objectType.setName("Note [Watch]"); 32 nullAny.setMeType("MENull"); 33 nullAny.setMeValue(""); 34 props[0] = nullAny; 35 textAny.setMeType("Text"); 36 textAny.setMeValue("'A new note created by the API'"); 37 values[0] = textAny; 38 np = area = nullAny; 39 try { 40 newObjectAny = port.instProps(objectType, props, values, np, area); 41 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 42 if(!newObjectAny.getMeType().equals("MEOop")) 43 System.exit(3); // No object created 44 StringTokenizer st = new StringTokenizer(newObjectAny.getMeValue(), "_", false); 45 newObject.setAreaID(Integer.parseInt(st.nextToken())); 46 newObject.setObjectID(Integer.parseInt(st.nextToken())); 47 try { 48 port.addToGraph(newObject, graphs[0]); 49 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 50 try { 51 diagrams = port.diagrams(graphs[0]); 52 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 53 if(diagrams.length == 0) System.exit(4); // No existing diagrams found 54 place.setMeType("Point"); 55 place.setMeValue("400,360"); 56 try { 57 port.addNewObjectRepFor(diagrams[0], newObject, 0,place); 58 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 59 try { 60 port.animate(graphs[0], newObject); 61 } catch (Exception ex) { System.err.println(ex.getMessage()); System.exit(1); } 62 } 63 }

To understand how the client works, please read on and follow the code after the various definitions from line 21 onwards. Lines 21-24 initialize the connection to MetaEdit+ API server. Steps 1 and 2, fetching all WatchFamily graphs, is taken care of in lines 26–30. Preparing for and carrying out creation of new object (steps 3 to 7) takes place in lines 31–43. The areaID and objectID for the new object are parsed in lines 44–46 and the object is attached into the graphs in lines 47–49 (steps 8 and 9). The possible diagrams are retrieved in lines 50–53, a new object representation created in lines 54–58 (steps 10 and 11), and the newly-created object highlighted in lines 59-61.

When compiling the code, we must remember to introduce the additional libraries. As an example of how this is done, see the batch file sample in Listing 3.

01 set path=%path%;c:\Program Files\Java\jdk1.7.0_51\bin 02 set axisdir=c:\java\axis-1_4 03 set xercesdir=c:\java\xerces-2_11_0 04 set classpath=%axisdir%\lib\*;%xercesdir%\*;. 05 java org.apache.axis.wsdl.WSDL2Java -p com.metacase.API MetaEdit.wsdl 06 javac APIExampleApp.java com\metacase\API\*.java

In the first three lines we set the paths for the Java compiler and Axis and Xerces libraries – remember to change these to match your installation directories. The classpath for the libraries is set in line 4. The next step is to use Axis’s WSDL2Java to translate the MetaEdit+ WSDL file into Java code (the WSDL file can be generated from MetaEdit+ API Tool and it should be named as MetaEdit.wsdl). This is done in line 5 (note that in this example the WSDL file is expected to be in the same directory as the sample Java code). The output from WSDL2Java is stored in the com\metacase\API directory. Finally, in line 6, we compile our APIExampleApp along with the WSDL2Java output.

To try out this API example, login to MetaEdit+, open the API Tool, and start the API server. Once that is running, make sure the ‘WatchModels’ WatchFamily diagram is closed, and execute the APIExampleApp. The ‘WatchModels’ diagram will open with the new Note object highlighted (as in Figure 9–2).

	The Apache Xerces2 XML parser for Java from xerces.apache.org (version 2.11.0 was used for this example). The example assumes it to be installed in c:\java\xerces-2_11_0 on Windows platforms (if you install it elsewhere, remember to edit the %xercesdir% variable in the compile and execution batch file shown in Listing 3).
	The Apache Axis SOAP library from axis.apache.org/axis (for this example, we used version 1.4 bin). It is assumed to be installed in c:\java\axis-1_4 (if located elsewhere, change %axisdir% variable in the batch file shown in Listing 3).