Project

General

Profile

1 1780 jones
/**
2
 *  '$RCSfile$'
3
 *  Copyright: 2000 Regents of the University of California and the
4
 *              National Center for Ecological Analysis and Synthesis
5
 *
6
 *   '$Author$'
7
 *     '$Date$'
8
 * '$Revision$'
9
 *
10
 * This program is free software; you can redistribute it and/or modify
11
 * it under the terms of the GNU General Public License as published by
12
 * the Free Software Foundation; either version 2 of the License, or
13
 * (at your option) any later version.
14
 *
15
 * This program is distributed in the hope that it will be useful,
16
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18
 * GNU General Public License for more details.
19
 *
20
 * You should have received a copy of the GNU General Public License
21
 * along with this program; if not, write to the Free Software
22
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
23
 */
24
25
package edu.ucsb.nceas.metacat.client;
26
27
import java.io.Reader;
28 1785 tao
import java.io.IOException;
29 1780 jones
30
/**
31
 *  This interface provides methods for initializing and logging in to a
32
 *  Metacat server, and then querying, reading, transforming, inserting,
33
 *  updating and deleting documents from that server.
34
 */
35
public interface Metacat
36
{
37
    /**
38
     *  Method used to log in to a metacat server. Implementations will need
39
     *  to cache a cookie value to make the session persistent.  Each time a
40
     *  call is made to one of the other methods (e.g., read), the cookie will
41
     *  need to be passed back to the metacat server along with the request.
42
     *
43
     *  @param username   the username of the user, like an LDAP DN
44
     *  @param password   the password for that user for authentication
45 1822 jones
     *  @return the response string from metacat in XML format
46 1780 jones
     *  @throws MetacatAuthException when the username/password could
47
     *                    not be authenticated
48
     */
49 1822 jones
    public String login(String username, String password)
50 1780 jones
           throws MetacatAuthException, MetacatInaccessibleException;
51 1797 tao
52
    /**
53 1822 jones
     *  Method used to log out a metacat server. The Metacat server will end
54
     *  the session when this call is invoked.
55 1797 tao
     *
56 1822 jones
     *  @return the response string from metacat in XML format
57 1797 tao
     *  @throws MetacatInaccessibleException when the metacat server can not be
58
     *                                    reached or does not respond
59
     */
60 1822 jones
    public String logout() throws MetacatInaccessibleException,
61
        MetacatException;
62 1780 jones
63
    /**
64
     * Read an XML document from the metacat server session, accessed by docid,
65
     * and returned as a Reader.
66
     *
67
     * @param docid the identifier of the document to be read
68
     * @return a Reader for accessing the document
69
     * @throws InsufficientKarmaException when the user has insufficent rights
70
     *                                    for the operation
71 1784 jones
     * @throws MetacatInaccessibleException when the metacat server can not be
72
     *                                    reached or does not respond
73
     * @throws MetacatException when the metacat server generates another error
74 1780 jones
     */
75 1784 jones
    public Reader read(String docid) throws InsufficientKarmaException,
76
        MetacatInaccessibleException, MetacatException;
77 1780 jones
78
    /**
79
     * Query the metacat document store with the given metacat-compatible
80
     * query document, and return the result set as a Reader.
81
     *
82
     * @param xmlQuery a Reader for accessing the XML version of the query
83
     * @return a Reader for accessing the result set
84
     */
85 1785 tao
    public Reader query(Reader xmlQuery) throws MetacatInaccessibleException,
86
                                                IOException;
87 1780 jones
88
    /**
89
     * Insert an XML document into the repository.
90
     *
91
     * @param docid the docid to insert the document
92
     * @param xmlDocument a Reader for accessing the XML document to be inserted
93
     * @param schema a Reader for accessing the DTD or XML Schema for
94
     *               the document
95 1789 jones
     * @return the metacat response message
96 1780 jones
     * @throws InsufficientKarmaException when the user has insufficent rights
97
     *                                    for the operation
98 1789 jones
     * @throws MetacatInaccessibleException when the metacat server can not be
99
     *                                    reached or does not respond
100
     * @throws MetacatException when the metacat server generates another error
101
     * @throws IOException when there is an error reading the xml document
102 1780 jones
     */
103 1789 jones
    public String insert(String docid, Reader xmlDocument, Reader schema)
104
        throws InsufficientKarmaException, MetacatException, IOException,
105
        MetacatInaccessibleException;
106 1780 jones
107
    /**
108
     * Update an XML document in the repository.
109
     *
110
     * @param docid the docid to update
111
     * @param xmlDocument a Reader for accessing the XML text to be updated
112
     * @param schema a Reader for accessing the DTD or XML Schema for
113
     *               the document
114 1795 jones
     * @return the metacat response message
115 1780 jones
     * @throws InsufficientKarmaException when the user has insufficent rights
116
     *                                    for the operation
117 1795 jones
     * @throws MetacatInaccessibleException when the metacat server can not be
118
     *                                    reached or does not respond
119
     * @throws MetacatException when the metacat server generates another error
120
     * @throws IOException when there is an error reading the xml document
121 1780 jones
     */
122 1795 jones
    public String update(String docid, Reader xmlDocument, Reader schema)
123
        throws InsufficientKarmaException, MetacatException, IOException,
124
        MetacatInaccessibleException;
125 1780 jones
126
    /**
127
     * Delete an XML document in the repository.
128
     *
129
     * @param docid the docid to delete
130 1795 jones
     * @return the metacat response message
131 1780 jones
     * @throws InsufficientKarmaException when the user has insufficent rights
132
     *                                    for the operation
133 1795 jones
     * @throws MetacatInaccessibleException when the metacat server can not be
134
     *                                    reached or does not respond
135
     * @throws MetacatException when the metacat server generates another error
136 1780 jones
     */
137 1795 jones
    public String delete(String docid)
138
        throws InsufficientKarmaException, MetacatException,
139
        MetacatInaccessibleException;
140 1780 jones
141
    /**
142
     * When the MetacatFactory creates an instance it needs to set the
143
     * MetacatUrl to which connections should be made.
144
     *
145
     * @param metacatUrl the URL for the metacat server
146
     */
147
    public void setMetacatUrl(String metacatUrl);
148 1822 jones
149
    /**
150
     * Get the session identifier for this session.
151
     *
152
     * @returns the sessionId as a String, or null if the session is invalid
153
     */
154
    public String getSessionId();
155 1826 jones
156
    /**
157
     * Set the session identifier for this session.  This identifier was
158
     * previously established with a call to login.  To continue to use the
159
     * same session, set the session id before making a call to one of the
160
     * metacat access methods (e.g., read, query, insert, etc.).
161
     *
162
     * @param String the sessionId from a previously established session
163
     */
164
    public void setSessionId(String sessionId);
165 1780 jones
}