001: package br.com.gfpshare.proxy.http;
002:
003: import java.io.File;
004: import java.io.FileNotFoundException;
005: import java.io.IOException;
006: import java.io.InputStream;
007:
008: /**
009: * Esta interface define operações básicas para comunicação
010: * utilizando o protocolo HTTP.
011: * O objetivo é implementar estas funcionalidades em um ponto
012: * central do GA, fornecendo uma espécie de "fachada" para as
013: * aplicações internas do GA que necessitem comunicar via HTTP. <p>
014: * Subclasse conhecida: {@link HttpClientDefault}
015: * @author f3568416
016: */
017: public interface GeneralHttpClient {
018:
019: /**
020: * Propriedade que identifica metodo GET
021: */
022: public final int HTTPCLIENT_GET_METHOD = 0;
023:
024: /**
025: * Propriedade que identifica metodo POST
026: */
027: public final int HTTPCLIENT_POST_METHOD = 2;
028:
029: /**
030: * Propriedade que identifica status execucao OK
031: */
032: public final int HTTPCLIENT_STATUS_OK = 200;
033:
034: public final int HTTPCLIENT_STATUS_NOTFOUND = 403;
035:
036: /**
037: * Configura o tempo maximo de espera por uma resposta
038: * do servidor.<p>
039: * Ex: setTimeout(5000) --->> espera 5 segundos
040: * @param t tempo em milissegundos
041: */
042: public void setTimeout(int t);
043:
044: /**
045: * Configura o numero maximo de tentativas AUTOMATICAS para
046: * re-executar uma requisicao em caso de erro na comunicacao.<p>
047: * ATENCAO - O uso desta opcao pode causar o envio repetido
048: * da mesma requisicao ao servidor, levando a inconsistencias em
049: * bases de dados, caso se trate de uma mensagem transacional.
050: * @param c numero de tentativas. <p>
051: * Se c==0 NAO sera' executada nenhuma tentativa AUTOMATICA
052: */
053: public void setRetryCount(int c);
054:
055: /**
056: * Adiciona um par nome-valor na requisicao. <p>
057: * Valido somente quando se utiliza o metodo {@link HTTPCLIENT_POST_METHOD}.
058: * Podem ser utilizados diversos pares nome-valor, conforme as
059: * necessidades da aplicacao.<p>
060: * OBSERVACAO - Este metodo e' mutuamente exclusivo
061: * com {@link #setPostRequestBody(String)},
062: * portanto deve-se este ou aquele.
063: * @param name um nome para compor o par nome-valor
064: * @param value um valor para compor o par nome-valor
065: * @see #addPostParameter(NameValue)
066: */
067: public void addPostParameter(String name, String value);
068:
069: /**
070: * Adiciona um par nome-valor na requisicao. <p>
071: * OBSERVACAO - Este metodo e' mutuamente exclusivo
072: * com {@link #setPostRequestBody(String)},
073: * portanto deve-se usar este ou aquele.
074: * @param nv um objeto NameValue contendo o par nome-valor
075: * @see #addPostParameter(String, String)
076: */
077: public void addPostParameter(NameValue[] nv);
078:
079: /**
080: * Adiciona um par nome-valor no cabecalho da requisicao.
081: * Podem ser utilizados diversos pares nome-valor, conforme as
082: * necessidades da aplicacao.
083: * @param name um nome para compor o par nome-valor
084: * @param value um valor para compor o par nome-valor
085: * @see #addRequestHeader(NameValue)
086: */
087: public void addRequestHeader(String name, String value);
088:
089: /**
090: * Adiciona um par nome-valor ao cabecalho da requisicao.
091: * @param nv um objeto NameValue contendo o par nome-valor
092: * @see #addRequestHeader(String, String)
093: */
094: public void addRequestHeader(NameValue[] nv);
095:
096: /**
097: * Seta o corpo da requisicao. <p>
098: * Valido somente quando se utiliza o metodo {@link HTTPCLIENT_POST_METHOD}.<p>
099: * OBSERVACAO - Este metodo e' mutuamente exclusivo
100: * com {@link #addPostParameter()} portanto deve-se usar este ou aqueles.
101: * @param body o corpo da requisicao
102: */
103: public void setPostRequestBody(String body);
104:
105: /**
106: * Inicializa recursos para efetuar uma requisicao.
107: * E' OBRIGATORIA a chamada a este metodo ANTES de se configurar
108: * parametros e dados de uma nova requisicao, ou seja, antes da
109: * chamada a {@link #executeRequest() } <p>
110: * Uma nova chamada a este metodo somente deve ser feita
111: * APOS o tratamento da resposta.<p>
112: * Exemplo dos passos necessarios:
113: * HttpClientGA cli = HttpClientGAFactory.getInstance();
114: * cli.setTimeout(15000);
115: * cli.setRetryCount(2);
116: * cli.initRequest(url,HttpClientGA.HTTPCLIENT_GET_METHOD);
117: * cli.executeRequest();
118: * //trata a resposta
119: * System.out.println(cli.getResponseBody());
120: * //inicia nova requisicao para a mesma ou outra url:
121: * cli.initRequest(url2,HttpClientGA.HTTPCLIENT_GET_METHOD);
122: * cli.executeRequest();
123: * //trata a resposta
124: * System.out.println(cli.getResponseBody());
125: * EXPLICACOES ADICIONAIS SOBRE A NECESSIDADE DESTE METODO:
126: * Isso e' necessario porque nao temos como liberar automaticamente
127: * os recursos apos cada executeRequest(), pois somente o usuario deste objeto
128: * sabe o momento exato da liberacaoa: apos execucao dos metodos que leem
129: * cabecalho, corpo e rodape da resposta. <p>
130: * Tambem nao podemos liberar automaticamente os recursos antes de
131: * cada executeRequest(), pois isso causaria a perda de todos parametros/dados
132: * configurados. <p>
133: * @param url uma url completa incluindo o campo protocolo, tal como http://
134: * @param method metodo a ser utilizado na comunicacao, o qual pode ser:
135: * - {@link HTTPCLIENT_GET_METHOD} ou <p>
136: * - {@link HTTPCLIENT_POST_METHOD}
137: */
138: public void initRequest(String url, int method);
139:
140: /**
141: * Envia a requisicao ao servidor. <p>
142: * Apos esta chamada deve-se utilizar {@link #getResponseBody()},
143: * {@link #getResponseHeaders()} ou {@link #getResponseFooters()},
144: * conforme a necessidade, para leitura dos dados recebidos. <p>
145: * OBSERVACAO: Este metodo pode ser chamado diversas vezes,
146: * desde que seja executado antes o metodo {@link #initRequest(String, int)}.
147: * Com isso, pode-se beneficiar-se de uma conexao já existente
148: * para um mesmo servidor.
149: * Antes da proxima execucao, informar novos dados para
150: * compor a requisicao. Ver {@link #initRequest(String, int)}
151: * @return um codigo que informa o status da execucao
152: * @throws IOException caso ocorra algum erro de comunicacao
153: * @see #initRequest(String, int)
154: * @see #getStatusCode()
155: * @see #getResponseBody()
156: * @see #getResponseHeaders()
157: * @see #getResponseFooters()
158: */
159: public int executeRequest() throws IOException;
160:
161: /**
162: * Obtem o codigo relativo ao status da ultima requisicao executada.
163: * @return valor do codigo de status
164: * @see GeneralHttpClient#HTTPCLIENT_STATUS_OK
165: */
166: public int getStatusCode();
167:
168: /**
169: * Obtem uma frase explicativa do status da ultima requisicao executada.
170: * @return texto explicativo do status
171: */
172: public String getStatusPhrase();
173:
174: /**
175: * Obtem o corpo da resposta da ultima requsicao executada.
176: * @return o corpo da resposta
177: * @throws IOException caso ocorra algum erro de comunicacao
178: */
179: public String getResponseBody() throws IOException;
180:
181: /**
182: * Obtem o corpo da resposta da ultima requisicao executada na forma
183: * de um InputStream
184: * @return um InputStream contendo o corpo da resposta
185: * @throws IOException caso ocorra algum erro de comunicacao
186: */
187: public InputStream getResponseBodyAsStream() throws IOException;
188:
189: /**
190: * Obtem o rodape' da resposta da ultima requisicao executada.
191: * @return o rodape' da resposta na forma de um array
192: * de objetos NameValue
193: * @throws IOException caso ocorra algum erro de comunicacao
194: */
195: public NameValue[] getResponseFooters() throws IOException;
196:
197: /**
198: * Obtem o cabecalho da resposta da ultima requisicao executada.
199: * @return o cabecalho da resposta na forma de um array
200: * de objetos NameValue
201: * @throws IOException caso ocorra algum erro de comunicacao
202: */
203: public NameValue[] getResponseHeaders() throws IOException;
204:
205: /**
206: * Obtem o rodape' da resposta da ultima requisicao executada.
207: * @return o rodape' da resposta na forma de uma unica string.
208: * @throws IOException caso ocorra algum erro de comunicacao
209: */
210: public String getResponseFootersAsString() throws IOException;
211:
212: /**
213: * Obtem o cabecalho da resposta da ultima requisicao executada.
214: * @return o cabecalho da resposta na forma de uma unica string.
215: * @throws IOException caso ocorra algum erro de comunicacao
216: */
217: public String getResponseHeadersAsString() throws IOException;
218:
219: /**
220: * Configura parametros para permitir autenticacao do requisitante
221: * por um servidor proxy, quando houver tal restricao. <p>
222: * Ex: acesso 'a internet a partir de uma rede interna.
223: * @param host nome ou endereco do servidor proxy
224: * @param port porta no servidor proxy
225: * @param user identificacao do usuario
226: * @param passwd senha do usuario
227: */
228: public void setProxyAuthorization(String host, int port,
229: String user, String passwd);
230:
231: /**
232: * Configura parametros para permitir autenticacao do requisitante
233: * pelo servidor destino da requisicao, quando houver tal restricao. <p>
234: * Ex: aplicacao destino faz controle de acesso
235: * @param user identificacao do usuario
236: * @param passwd senha do usuario
237: */
238: public void setServerAuthorization(String user, String passwd);
239:
240: /**
241: * Seta o endereço e porta do porxy
242: * @param ip
243: * @param port
244: */
245: public void setProxy(String ip, int port);
246:
247: /**
248: * Tem que ser o ultimo método a ser
249: * chamado para adcionar parametros ao post
250: * @param targetFile
251: * @throws FileNotFoundException
252: */
253: public void fileUpload(String paramName, File targetFile)
254: throws FileNotFoundException;
255:
256: }
|