/*
* GeoTools - The Open Source Java GIS Toolkit
* http://geotools.org
*
* (C) 2004-2008, Open Source Geospatial Foundation (OSGeo)
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation;
* version 2.1 of the License.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*/
package org.geotools.data.ows;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URL;
import java.util.Properties;
import org.geotools.ows.ServiceException;
/**
* This represents a Request to be made against a Open Web Service.
*
* @author rgould
*
* @source $URL$
*/
public interface Request {
/** Represents the REQUEST parameter */
public static final String REQUEST = "REQUEST"; //$NON-NLS-1$
/** Represents the VERSION parameter */
public static final String VERSION = "VERSION"; //$NON-NLS-1$
/** Represents the WMTVER parameter */
public static final String WMTVER = "WMTVER"; //$NON-NLS-1$
public static final String SERVICE = "SERVICE";
/**
* Once the properties of the request are configured, this will return
* the URL that points to the server and contains all of the appropriate
* name/value parameters.
*
* @return a URL that can be used to issue the request
*/
public URL getFinalURL();
/**
* Sets the name/value property for this request.
*
* Note that when using this method, it is up to the programmer to
* provide their own encoding of <code>value</code> according to the
* OWS specifications! The code will not do this for you.
*
* Different OWS specifications define different ways to do this. There are
* notorious differences between WMS 1.1.1 (section 6.2.1) and
* WMS 1.3.0 (section 6.3.2) for example.
*
* If value is null, "name" is removed from the properties table.
*
* @param name the name of the property
* @param value the value of the property
*/
public void setProperty(String name, String value);
/**
* @return a copy of this request's properties
*/
public Properties getProperties();
/**
* Each Request must know how to create it's counterpart Response.
* Given the content type and input stream (containin the response data),
* this method must return an appropriate Response object.
*
* @param contentType the MIME type of the data in the inputStream
* @param inputStream contains the data from the response
* @throws ServiceException
* @throws IOException
*/
Response createResponse(String contentType, InputStream inputStream) throws ServiceException, IOException;
/**
* This method indicates whether this request needs to transmit some data
* to the server using POST. If this returns true, performPostOutput() will be called
* during the connection, allowing the data to be written out to the server.
*
* @return true if this request needs POST support, false otherwise.
*/
boolean requiresPost();
/**
* If this request uses POST, it must specify the content type of the data
* that is to be written out during performPostOutput().
*
* For open web services, this is usually "application/xml".
*
* @return the MIME type of the data to be sent during the request
*/
String getPostContentType();
/**
* This is called during the connection to the server, allowing this
* request to write out data to the server by using the provided
* outputStream.
*
* Implementors of this method do not need to call outputStream.flush() or
* outputStream.close(). The framework will call them immediately after
* calling this method.
*
* @param outputStream
*/
void performPostOutput(OutputStream outputStream) throws IOException;
}