Metacat provides a client programming interface for communicating with the server. The client API is available in Java and Perl, but the Java interface will be described here. This interface allows a client application to easily authenticate users and perform basic metacat operations such as reading metadata and data files, inserting, updating, and deleting files, and searching for packages based on metadata matches.

To use the client, developers must include the 'metacat-client.jar', 'utilities.jar', and 'httpclient.jar' in their classpath. Then, the API methods can be used. For example, a typical session to read a document from the database might look like this:

        String metacatUrl = "http://foo.com/context/metacat";
        String username = "uid=jones,o=NCEAS,dc=ecoinformatics,dc=org";
        String password = "neverHarcodeAPasswordInCode";
        try {
            Metacat m = MetacatFactory.createMetacatConnection(metacatUrl);
            m.login(username, password);
            Reader r = m.read("testdocument.1.1");
            // Do whatever you want with Reader r
        } catch (MetacatAuthException mae) {
            handleError("Authorization failed:\n" + mae.getMessage());
        } catch (MetacatInaccessibleException mie) {
            handleError("Metacat Inaccessible:\n" + mie.getMessage());
        } catch (Exception e) {
            handleError("General exception:\n" + e.getMessage());
        }
     

The Client API is defined by the interface edu.ucsb.nceas.metacat.client.Metacat, and all operations are fully defined inthe javadoc documentation. Briefly, the API provides the following operations:

• public String login(String username, String password) throws MetacatAuthException, MetacatInaccessibleException;
• public String logout() throws MetacatInaccessibleException, MetacatException;
• public Reader read(String docid) throws InsufficientKarmaException, MetacatInaccessibleException, MetacatException;
• public Reader readInlineData(String inlinedataid) throws InsufficientKarmaException, MetacatInaccessibleException, MetacatException;
• public Reader query(Reader xmlQuery) throws MetacatInaccessibleException, IOException;
• public String insert(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;
• public String update(String docid, Reader xmlDocument, Reader schema) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;
• public String upload(String docid, File file) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;
• public String upload(String docid, String fileName, InputStream fileData, int size) throws InsufficientKarmaException, MetacatException, IOException, MetacatInaccessibleException;
• public String delete(String docid) throws InsufficientKarmaException, MetacatException, MetacatInaccessibleException;
• public void setMetacatUrl(String metacatUrl);
• public String getSessionId();
• public void setSessionId(String sessionId);
• public int getNewestDocRevision(String docId) throws MetacatException;
• public String setAccess(String docid, String principal, String permission, String permType, String permOrder );