1 /**
2 * Copyright (C) 2005-2009 Alfresco Software Limited.
3 *
4 * This file is part of the Spring Surf Extension project.
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.springframework.extensions.webscripts.connector;
20
21 import java.io.InputStream;
22 import java.io.OutputStream;
23
24 import javax.servlet.http.HttpServletRequest;
25 import javax.servlet.http.HttpServletResponse;
26
27 /**
28 * Describes a connector to a remote endpoint for a given user.
29 *
30 * All connectors are scoped to a particular user and a particular
31 * endpoint. As such, their endpoints and user bindings cannot
32 * be swapped once they are created. Rather, you should create
33 * new connectors for new users and new endpoints.
34 *
35 * A connector is scoped to a given user and a given endpoint.
36 *
37 * All calls using a connector will be stamped with a user's
38 * connector credentials. These connector credentials usually consist
39 * of things like cookies, tokens, additional request parameters and
40 * other HTTP request state.
41 *
42 * The caller does not have to pass this data manually. It is managed
43 * for the developer by the underlying ConnectorService during the
44 * factory construction of Connector objects.
45 *
46 * If a connector is constructed without user information, then it is scoped to
47 * a null user. No credential information is passed through and the connections
48 * are anonymous.
49 *
50 * @author muzquiano
51 */
52 public interface Connector
53 {
54 /**
55 * Invokes a URI on a remote service.
56 *
57 * The response data is buffered into a data element on the returned
58 * object of type Response.
59 *
60 * @param uri the uri
61 *
62 * @return the response
63 */
64 public Response call(String uri);
65
66 /**
67 * Invokes a URI on a remote service.
68 * If the context is null, then it will not be utilized.
69 *
70 * The response data is buffered into a data element on the returned
71 * object of type Response.
72 *
73 * @param uri the uri
74 * @param context the context of the invoke
75 *
76 * @return the response
77 */
78 public Response call(String uri, ConnectorContext context);
79
80 /**
81 * Invokes a URI on a remote service, passing the input as supplied via
82 * a POST/PUT.
83 *
84 * If the context is null, then it will not be utilized and POST will
85 * be assumed.
86 *
87 * The response data is buffered into a data element on the returned
88 * object of type Response.
89 *
90 * @param uri the uri
91 * @param context the context of the invoke
92 * @param in the input stream
93 *
94 * @return the response
95 */
96 public Response call(String uri, ConnectorContext context, InputStream in);
97
98 /**
99 * Invokes a URI on a remote service. Data is streamed back from the
100 * response into the provided output stream. Headers and response state
101 * is maintained on the Response object.
102 *
103 * If the context is null, then it will not be utilized.
104 *
105 * The response data is not buffered
106 *
107 * @param uri the uri
108 * @param context the context of the invoke
109 * @param in the input stream
110 * @param out the output stream
111 *
112 * @return the response
113 */
114 public Response call(String uri, ConnectorContext context, InputStream in, OutputStream out);
115
116 /**
117 * Invokes a URI on a remote service and streams back results to the
118 * provided response object. This method makes sure that the full
119 * response is propagated into the servlet response, including headers,
120 * exception states and more.
121 *
122 * If the context is null, then it will not be utilized.
123 *
124 * The response data is not buffered.
125 *
126 * @param uri the uri
127 * @param context the context of the invoke
128 * @param req Request to proxy from
129 * @param res Response to proxy onto
130 *
131 * @return the response
132 */
133 public Response call(String uri, ConnectorContext context, HttpServletRequest req, HttpServletResponse res);
134
135 /**
136 * Binds Credentials to this connector.
137 *
138 * @param credentials the new credentials
139 */
140 public void setCredentials(Credentials credentials);
141
142 /**
143 * Returns the credents for this connector.
144 *
145 * @return the credentials
146 */
147 public Credentials getCredentials();
148
149 /**
150 * Sets the endpoint.
151 *
152 * @param endpoint the new endpoint
153 */
154 public void setEndpoint(String endpoint);
155
156 /**
157 * Returns the endpoint to which this connector connects.
158 *
159 * @return endpoint the endpoint
160 */
161 public String getEndpoint();
162
163 /**
164 * Sets the connector session
165 *
166 * @param connectorSession
167 */
168 public void setConnectorSession(ConnectorSession connectorSession);
169
170 /**
171 * Returns the connector session
172 *
173 * @return the connector session
174 */
175 public ConnectorSession getConnectorSession();
176 }