1 <?php
2 /*
3 Copyright (c) 2012, University of Cambridge Computing Service
4
5 This file is part of the Lookup/Ibis client library.
6
7 This library is free software: you can redistribute it and/or modify
8 it under the terms of the GNU Lesser General Public License as published
9 by the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
11
12 This library is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
14 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
15 License for more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with this library. If not, see <http://www.gnu.org/licenses/>.
19 */
20
21 /**
22 * Interface representing a connection to the Lookup/Ibis server, capable
23 * of invoking methods on the web service API and unmarshalling the results.
24 *
25 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
26 */
27 interface ClientConnection
28 {
29 /**
30 * Set the username to use when connecting to the Lookup/Ibis web service.
31 * By default connections are anonymous, which gives read-only access.
32 * This method enables authentication as a group, using the group's
33 * password, which gives read/write access and also access to certain
34 * non-public data, based on the group's privileges.
35 *
36 * This method may be called at any time, and affects all subsequent
37 * access using this connection, but should not affect any other
38 * ClientConnection objects.
39 *
40 * @param string $username The username to connect as. This should either
41 * be ``"anonymous"`` (the default) or the name of a group.
42 * @return void
43 */
44 public function setUsername($username);
45
46 /**
47 * Set the password to use when connecting to the Lookup/Ibis web service.
48 * This is only necessary when connecting as a group, in which case it
49 * should be that group's password.
50 *
51 * @param string $password The group password.
52 * @return void
53 */
54 public function setPassword($password);
55
56 /**
57 * Invoke a web service GET method.
58 *
59 * The path should be the relative path to the method with standard
60 * Java/PHP format specifiers for any path parameters, for example
61 * ``"api/v1/person/%1$s/%2$s"``. Any path parameters specified
62 * are then substituted into the path according to the standard Java
63 * formatting rules.
64 *
65 * @param string $path The path to the method to invoke.
66 * @param string[] $pathParams Any path parameters that should be inserted
67 * into the path in place of any format specifiers.
68 * @param array $queryParams Any query parameters to add as part of the
69 * URL's query string.
70 * @return IbisResult The result of invoking the method.
71 */
72 public function invokeGetMethod($path, $pathParams, $queryParams);
73
74 /**
75 * Invoke a web service GET, POST, PUT or DELETE method.
76 *
77 * The path should be the relative path to the method with standard
78 * Java/PHP format specifiers for any path parameters, for example
79 * ``"api/v1/person/%1$s/%2$s"``. Any path parameters specified
80 * are then substituted into the path according to the standard Java
81 * formatting rules.
82 *
83 * @param string $method The method type (``"GET"``, ``"POST"``,
84 * ``"PUT"`` or ``"DELETE"``).
85 * @param string $path The path to the method to invoke.
86 * @param string[] $pathParams Any path parameters that should be inserted
87 * into the path in place of any format specifiers.
88 * @param array $queryParams Any query parameters to add as part of the
89 * URL's query string.
90 * @param array $formParams Any form parameters to submit.
91 * @return IbisResult The result of invoking the method.
92 */
93 public function invokeMethod($method, $path, $pathParams,
94 $queryParams, $formParams);
95 }
96