Project

General

Profile

Revision 2310

Added new sections to the Metacat documentation describing the Metacat
client API and the Metacat 'getlog' servlet action for event reporting.

View differences:

docs/user/acontrol.html
44 44
      <li> Metacat also allows document level access control via Access Control 
45 45
      Lists (ACLs).</li>
46 46
    </ul>
47
  <p style="color: red; font-face: bold">WARNING: The rest of this page is 
48
   out-of-date and no longer accurate. It is left only for reference purposes.
49
   ACL information is now set through EML 2.0.0 access control elements.
50
  </p>
47 51
  <!--<img src="acontrol.gif">-->
48 52
  <b>ACLs</b>
49 53
  <p>Metacat allows a user to set permissions for users or groups on individual 
docs/user/metacattour.html
50 50
      <li> <a href="./metacat.html">Metacat Server</a></li>
51 51
      <li> <a href="./metacatdb.html">Metacat Database</a></li>
52 52
      <li> <a href="./metacatdom.html">Metacat Document Object Model (DOM)</a></li>
53
      <li> <a href="./clientapi.html">Metacat Client Programming Interface</a></li>
53 54
      <li> <a href="./metacatload.html">Writing XML</a></li>
54 55
      <li> <a href="./metacatquery.html">Searching the Database</a></li>
55 56
      <li> <a href="./metacatread.html">Reading data from Metacat</a></li>
57
      <li> <a href="./metacatgetlog.html">Event Log Reporting</a></li>
56 58
    </ul>
57 59
  </td>
58 60
</tr>
docs/user/metacatread.html
23 23
       from the Database</p></td>
24 24
       <td class="tablehead" colspan="2" align="right">
25 25
         <a href="./metacatquery.html">Back</a> | <a href="./metacattour.html">Home</a> | 
26
         <a href="./saxparser.html">Next</a>
26
         <a href="./metacatgetlog.html">Next</a>
27 27
       </td>
28 28
    </tr>
29 29
  </table>
......
79 79
  </p>
80 80
  <br>
81 81
  <a href="./metacatquery.html">Back</a> | <a href="./metacattour.html">Home</a> | 
82
  <a href="./saxparser.html">Next</a>
82
  <a href="./metacatgetlog.html">Next</a>
83 83

  
84 84
</BODY>
85 85
</HTML>
docs/user/metacatdom.html
22 22
      <td class="tablehead" colspan="2"><p class="label">The Metacat DOM</p></td>
23 23
      <td class="tablehead" colspan="2" align="right">
24 24
        <a href="./metacatdb.html">Back</a> | <a href="./metacattour.html">Home</a> | 
25
        <a href="./metacatload.html">Next</a>
25
        <a href="./clientapi.html">Next</a>
26 26
      </td>
27 27
    </tr>
28 28
  </table>
......
57 57
  
58 58
  <br>
59 59
  <a href="./metacatdb.html">Back</a> | <a href="./metacattour.html">Home</a> | 
60
  <a href="./metacatload.html">Next</a>
60
  <a href="./clientapi.html">Next</a>
61 61
</BODY>
62 62
</HTML>
63 63

  
docs/user/metacatload.html
21 21
    <tr>
22 22
      <td class="tablehead" colspan="2"><p class="label">Document Loading</p></td>
23 23
      <td class="tablehead" colspan="2" align="right">
24
        <a href="./metacatdom.html">Back</a> | <a href="./metacattour.html">Home</a> | 
24
        <a href="./clientapi.html">Back</a> | <a href="./metacattour.html">Home</a> | 
25 25
        <a href="./metacatquery.html">Next</a>
26 26
      </td>
27 27
    </tr>
......
113 113
  on the storage of XML documents.</p>
114 114

  
115 115
  <br>
116
  <a href="./metacatdom.html">Back</a> | <a href="./metacattour.html">Home</a> | 
116
  <a href="./clientapi.html">Back</a> | <a href="./metacattour.html">Home</a> | 
117 117
  <a href="./metacatquery.html">Next</a>
118 118
  
119 119
</BODY>
docs/user/metacatgetlog.html
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$'
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
23
       getlog action</p></td>
24
       <td class="tablehead" colspan="2" align="right">
25
         <a href="./metacatread.html">Back</a> | <a href="./metacattour.html">Home</a> | 
26
         <a href="./saxparser.html">Next</a>
27
       </td>
28
    </tr>
29
  </table>
30
  <p>
31
	The Metacat servlet provides an 'action' for retrieving a log of the
32
        events that have occurred, including document insertions, updates,
33
        deletes, and reads.  This allows a simple reporting facility where
34
        event reports can be output in XML format.  The report can be subset to
35
        only include events from a particular IP address, user, event type,
36
        after a start date, or before an end date.
37
  </p>
38
  <p>
39
	The basic log can be viewed using the <code>getlog</code> servlet 
40
	action, as in the following URL:<br>
41
     	<code>http://some.metacat.host/context/metacat?action=getlog</code>
42
  </p>
43
  <p>
44
  	This will return an XML formatted log of all events since the log was
45
	initiated, which can be quite extensive.  To subset the report, provide
46
        parameters to restrict the set of matching events:
47
        <ul>
48
        <li>ipAddress -- restrict the report to this ipAddress (repeatable)</li>
49
        <li>principal -- restrict the report to this principal (repeatable)</li>
50
        <li>docid -- restrict the report to this docid (repeatable)</li>
51
        <li>event -- restrict the report to this event type (repeatable)
52
            <ul>
53
            <li><code>insert</code></li>
54
            <li><code>update</code></li>
55
            <li><code>delete</code></li>
56
            <li><code>read</code></li>
57
            </ul>
58
        </li>
59
        <li>start -- restrict the report to events after this date
60
            <ul>
61
            <li><code>YYYY-MM-DD+hh:mm:ss</code></li>
62
            </ul>
63
        </li>
64
        <li>end -- restrict the report to events before this date
65
            <ul>
66
            <li><code>YYYY-MM-DD+hh:mm:ss</code></li>
67
            </ul>
68
        </li>
69
        </ul>
70
  </p>
71
  <p>
72
	Some example queries follow.  To view only the 'read' events, use a url like:<br>
73
     	<code>http://some.metacat.host/context/metacat?action=getlog&event=read</code>
74
  </p>
75
  <p>
76
	To view only the events for a particular IP address, use a url like:<br>
77
     	<code>http://some.metacat.host/context/metacat?action=getlog&ipaddress=107.9.1.31</code>
78
  </p>
79
  <p>
80
	To view only the events for a given user, use a url like:<br>
81
     	<code>http://some.metacat.host/context/metacat?action=getlog&principal=uid=johndoe,o=NCEAS,dc=ecoinformatics,dc=org</code>
82
  </p>
83
  <p>
84
	To view only the events for a particular document, use a url like:<br>
85
     	<code>http://some.metacat.host/context/metacat?action=getlog&docid=knb.5.1</code>
86
  </p>
87
  <p>
88
	To view only the events after a given date, use a url like:<br>
89
     	<code>http://some.metacat.host/context/metacat?action=getlog&start=2004-09-15+12:00:00</code>
90
  </p>
91
  <p>
92
	To view only the events before a given date, use a url like:<br>
93
     	<code>http://some.metacat.host/context/metacat?action=getlog&end=2004-09-15+12:00:00</code>
94
  </p>
95
  <p>
96
	Query parameters can be combined, so to view the 'insert' events for September 2004 use a url like:<br>
97
     	<code>http://some.metacat.host/context/metacat?action=getlog&event=insert&start=2004-09-01+12:00:00&end=2004-09-30+23:59:59</code>
98
  </p>
99
  <p>
100
	The log is returned in XML format.  Here is an example log format:<br>
101
        <pre>
102
&lt;?xml version="1.0"?&gt;
103
&lt;log&gt;
104
&lt;logEntry&gt;&lt;entryid&gt;44&lt;/entryid&gt;&lt;ipAddress&gt;34.237.20.142&lt;/ipAddress&gt;&lt;principal&gt;uid=jones,o=NCEAS,dc=ecoinformatics,dc=org&lt;/principal&gt;&lt;docid&gt;esa.2.1&lt;/docid&gt;&lt;event&gt;insert&lt;/event&gt;&lt;dateLogged&gt;2004-09-08 19:08:18.16&lt;/dateLogged&gt;&lt;/logEntry&gt;
105
&lt;logEntry&gt;&lt;entryid&gt;47&lt;/entryid&gt;&lt;ipAddress&gt;34.237.20.142&lt;/ipAddress&gt;&lt;principal&gt;uid=jones,o=NCEAS,dc=ecoinformatics,dc=org&lt;/principal&gt;&lt;docid&gt;esa.3.1&lt;/docid&gt;&lt;event&gt;insert&lt;/event&gt;&lt;dateLogged&gt;2004-09-14 19:50:40.61&lt;/dateLogged&gt;&lt;/logEntry&gt;
106
&lt;/log&gt;
107

  
108
        </pre>
109
  </p>
110
  <br>
111
  <a href="./metacatread.html">Back</a> | <a href="./metacattour.html">Home</a> | 
112
  <a href="./saxparser.html">Next</a>
113

  
114
</BODY>
115
</HTML>
116

  
0 117

  
docs/user/saxparser.html
21 21
    <tr>
22 22
      <td class="tablehead" colspan="2"><p class="label">XML Parsing with SAX</p></td>
23 23
      <td class="tablehead" colspan="2" align="right">
24
        <a href="./metacatread.html">Back</a> | <a href="./metacattour.html">Home</a> | 
24
        <a href="./metacatgetlog.html">Back</a> | <a href="./metacattour.html">Home</a> | 
25 25
        <a href="./xmlindex.html">Next</a>
26 26
      </td>
27 27
    </tr>
......
69 69
  </PRE>
70 70
  
71 71
  <br>
72
  <a href="./metacatread.html">Back</a> | <a href="./metacattour.html">Home</a> | 
72
  <a href="./metacatgetlog.html">Back</a> | <a href="./metacattour.html">Home</a> | 
73 73
  <a href="./xmlindex.html">Next</a>
74 74
  
75 75
</BODY>
docs/user/clientapi.html
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$'
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
  </ul>
95
  <br>
96
  <a href="./metacatdom.html">Back</a> | <a href="./metacattour.html">Home</a> | 
97
  <a href="./metacatload.html">Next</a>
98

  
99
</BODY>
100
</HTML>
101

  
0 102

  

Also available in: Unified diff