Project

General

Profile

metacat / docs / user / clientapi.html @ 3067

1
<!--
2
  * metacatread.html
3
  *
4
  *      Authors: Jivka Bojilova
5
  *    Copyright: 2000 Regents of the University of California and the
6
  *               National Center for Ecological Analysis and Synthesis
7
  *  For Details: http://www.nceas.ucsb.edu/
8
  *      Created: 2000 April 5
9
  *      Version: 0.01
10
  *    File Info: '$Id: clientapi.html 2463 2005-04-06 21:38:38Z sgarg $'
11
  * 
12
  * October Meeting SDSC, 2000
13
-->
14
<HTML>
15
<HEAD>
16
<TITLE>Metacat</TITLE>
17
<link rel="stylesheet" type="text/css" href="@docrooturl@default.css">
18
</HEAD> 
19
<BODY>
20
  <table width="100%">
21
    <tr>
22
      <td class="tablehead" colspan="2"><p class="label">Metacat Client
23
       Application Programming Interface</p></td>
24
       <td class="tablehead" colspan="2" align="right">
25
         <a href="./metacatdom.html">Back</a> | <a href="./metacattour.html">Home</a> | 
26
         <a href="./metacatload.html">Next</a>
27
       </td>
28
    </tr>
29
  </table>
30
  <p>Metacat provides a client programming interface for communicating with
31
     the server.  The client API is available in Java and Perl, but the
32
     Java interface will be described here. This interface allows a client
33
     application to easily authenticate users and perform basic metacat
34
     operations such as reading metadata and data files, inserting, updating,
35
     and deleting files, and searching for packages based on metadata matches.
36
  </p>
37
  <p>To use the client, developers must include the 'metacat-client.jar',
38
     'utilities.jar',  and 'httpclient.jar' in their classpath.  Then, the API
39
     methods can be used.  For example, a typical session to read a document
40
     from the database might look like this:<br>
41
     <pre>
42
        String metacatUrl = "http://foo.com/context/metacat";
43
        String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org";
44
        String password = "neverHarcodeAPasswordInCode";
45
        try {
46
            Metacat m = MetacatFactory.createMetacatConnection(metacatUrl);
47
            m.login(username, password);
48
            Reader r = m.read("testdocument.1.1");
49
            // Do whatever you want with Reader r
50
        } catch (MetacatAuthException mae) {
51
            handleError("Authorization failed:\n" + mae.getMessage());
52
        } catch (MetacatInaccessibleException mie) {
53
            handleError("Metacat Inaccessible:\n" + mie.getMessage());
54
        } catch (Exception e) {
55
            handleError("General exception:\n" + e.getMessage());
56
        }
57
     </pre>
58
  </p>
59
  <p>The Client API is defined by the interface
60
     <code>edu.ucsb.nceas.metacat.client.Metacat</code>, and all operations
61
     are fully defined inthe javadoc documentation.  Briefly, the API 
62
     provides the following operations:</p>
63
    <ul>
64
    <li><code>public String <b>login</b>(String username, String password)
65
           throws MetacatAuthException, MetacatInaccessibleException;</code></li>
66
    <li><code>public String <b>logout</b>() throws MetacatInaccessibleException,
67
        MetacatException;</code></li>
68
    <li><code>public Reader <b>read</b>(String docid) throws InsufficientKarmaException,
69
        MetacatInaccessibleException, MetacatException;</code></li>
70
    <li><code>public Reader <b>readInlineData</b>(String inlinedataid)
71
        throws InsufficientKarmaException,
72
        MetacatInaccessibleException, MetacatException;</code></li>
73
    <li><code>public Reader <b>query</b>(Reader xmlQuery) throws MetacatInaccessibleException,
74
                                                IOException;</code></li>
75
    <li><code>public String <b>insert</b>(String docid, Reader xmlDocument, Reader schema)
76
        throws InsufficientKarmaException, MetacatException, IOException,
77
        MetacatInaccessibleException;</code></li>
78
    <li><code>public String <b>update</b>(String docid, Reader xmlDocument, Reader schema)
79
        throws InsufficientKarmaException, MetacatException, IOException,
80
        MetacatInaccessibleException;</code></li>
81
    <li><code>public String <b>upload</b>(String docid, File file)
82
        throws InsufficientKarmaException, MetacatException, IOException,
83
        MetacatInaccessibleException;</code></li>
84
    <li><code>public String <b>upload</b>(String docid, String fileName,
85
                         InputStream fileData, int size)
86
        throws InsufficientKarmaException, MetacatException, IOException,
87
        MetacatInaccessibleException;</code></li>
88
    <li><code>public String <b>delete</b>(String docid)
89
        throws InsufficientKarmaException, MetacatException,
90
        MetacatInaccessibleException;</code></li>
91
    <li><code>public void <b>setMetacatUrl</b>(String metacatUrl);</code></li>
92
    <li><code>public String <b>getSessionId</b>();</code></li>
93
    <li><code>public void <b>setSessionId</b>(String sessionId);</code></li>
94
    <li><code>public int <b>getNewestDocRevision</b>(String docId) throws MetacatException;</code></li>
95
    <li><code>public String <b>setAccess</b>(String docid, String principal, String permission, String permType, String permOrder );</code></li>
96
  </ul>
97
  <br>
98
  <a href="./metacatdom.html">Back</a> | <a href="./metacattour.html">Home</a> | 
99
  <a href="./metacatload.html">Next</a>
100

    
101
</BODY>
102
</HTML>
103