/* The contents of this file are subject to the license and copyright terms
* detailed in the license directory at the root of the source tree (also
* available online at http://fedora-commons.org/license/).
*/
package fedora.client;
import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.UnsupportedEncodingException;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLEncoder;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.ResourceBundle;
import java.util.TimeZone;
import javax.xml.rpc.ServiceException;
import org.apache.commons.httpclient.Header;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.MultiThreadedHttpConnectionManager;
import org.apache.commons.httpclient.UsernamePasswordCredentials;
import org.apache.commons.httpclient.auth.AuthScope;
import org.apache.commons.httpclient.methods.GetMethod;
import org.apache.commons.httpclient.methods.HeadMethod;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.multipart.FilePart;
import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
import org.apache.commons.httpclient.methods.multipart.Part;
import org.apache.log4j.Logger;
import org.jrdf.graph.Literal;
import org.jrdf.graph.Node;
import org.trippi.RDFFormat;
import org.trippi.TrippiException;
import org.trippi.TupleIterator;
import fedora.common.Constants;
import fedora.server.access.FedoraAPIA;
import fedora.server.management.FedoraAPIM;
import fedora.server.utilities.DateUtility;
/**
* General-purpose utility class for Fedora clients. Provides methods to get
* SOAP stubs for Fedora APIs. Also serves as one-stop-shopping for issuing HTTP
* requests using Apache's HttpClient. Provides option for client to handle HTTP
* redirects (notably 302 status that occurs with SSL auto-redirects at server.)
*
* @author Chris Wilper
* @author Sandy Payette
*/
public class FedoraClient
implements Constants {
public static final String FEDORA_URI_PREFIX = "info:fedora/";
/**
* Should FedoraClient take over log4j configuration?
* <h2>Deprecated as of Fedora 2.2</h2>
* FedoraClient no longer takes over Log4J configuration, and setting this
* value has no effect. Applications that use this class should configure
* Log4J themselves, or make a log4j.xml or log4j.properties file available
* from the runtime CLASSPATH.
*/
@Deprecated
public static boolean FORCE_LOG4J_CONFIGURATION = false;
/** Seconds to wait before a connection is established. */
public int TIMEOUT_SECONDS = 20;
/** Seconds to wait while waiting for data over the socket (SO_TIMEOUT). */
public int SOCKET_TIMEOUT_SECONDS = 1800; // 30 minutes
/** Maxiumum http connections per host (for REST calls only). */
public int MAX_CONNECTIONS_PER_HOST = 15;
/** Maxiumum total http connections (for REST calls only). */
public int MAX_TOTAL_CONNECTIONS = 30;
/** Whether to automatically follow HTTP redirects. */
public boolean FOLLOW_REDIRECTS = true;
/** Logger for this class. */
private static final Logger LOG =
Logger.getLogger(FedoraClient.class.getName());
private final SOAPEndpoint m_accessEndpoint = new SOAPEndpoint("access");
private final SOAPEndpoint m_managementEndpoint =
new SOAPEndpoint("management");
private String m_baseURL;
private final String m_user;
private final String m_pass;
private final AuthScope m_authScope;
private final UsernamePasswordCredentials m_creds;
private final MultiThreadedHttpConnectionManager m_cManager;
private String m_serverVersion;
/**
* Location of Fedora's upload interface, set on first call to
* getUploadURL().
*/
private String m_uploadURL;
public FedoraClient(String baseURL, String user, String pass)
throws MalformedURLException {
m_baseURL = baseURL;
m_user = user;
m_pass = pass;
if (!baseURL.endsWith("/")) {
m_baseURL += "/";
}
URL url = new URL(m_baseURL);
m_authScope =
new AuthScope(url.getHost(),
AuthScope.ANY_PORT,
AuthScope.ANY_REALM);
m_creds = new UsernamePasswordCredentials(user, pass);
m_cManager = new MultiThreadedHttpConnectionManager();
}
public HttpClient getHttpClient() {
m_cManager.getParams()
.setDefaultMaxConnectionsPerHost(MAX_CONNECTIONS_PER_HOST);
m_cManager.getParams().setMaxTotalConnections(MAX_TOTAL_CONNECTIONS);
m_cManager.getParams().setConnectionTimeout(TIMEOUT_SECONDS * 1000);
m_cManager.getParams().setSoTimeout(SOCKET_TIMEOUT_SECONDS * 1000);
HttpClient client = new HttpClient(m_cManager);
client.getState().setCredentials(m_authScope, m_creds);
client.getParams().setAuthenticationPreemptive(true);
return client;
}
/**
* Upload the given file to Fedora's upload interface via HTTP POST.
*
* @return the temporary id which can then be passed to API-M requests as a
* URL. It will look like uploaded://123
*/
public String uploadFile(File file) throws IOException {
PostMethod post = null;
try {
// prepare the post method
post = new PostMethod(getUploadURL());
post.setDoAuthentication(true);
post.getParams().setParameter("Connection", "Keep-Alive");
// chunked encoding is not required by the Fedora server,
// but makes uploading very large files possible
post.setContentChunked(true);
// add the file part
Part[] parts = {new FilePart("file", file)};
post.setRequestEntity(new MultipartRequestEntity(parts, post
.getParams()));
// execute and get the response
int responseCode = getHttpClient().executeMethod(post);
String body = null;
try {
body = post.getResponseBodyAsString();
} catch (Exception e) {
LOG.warn("Error reading response body", e);
}
if (body == null) {
body = "[empty response body]";
}
body = body.trim();
if (responseCode != HttpStatus.SC_CREATED) {
throw new IOException("Upload failed: "
+ HttpStatus.getStatusText(responseCode) + ": "
+ replaceNewlines(body, " "));
} else {
return replaceNewlines(body, "");
}
} finally {
if (post != null) {
post.releaseConnection();
}
}
}
/**
* Replace newlines with the given string.
*/
private static String replaceNewlines(String in, String replaceWith) {
return in.replaceAll("\r", replaceWith).replaceAll("\n", replaceWith);
}
/**
* Get the URL to which API-M upload requests will be sent.
*/
public synchronized String getUploadURL() throws IOException {
if (m_uploadURL != null) {
return m_uploadURL;
} else {
m_uploadURL = m_baseURL + "management/upload";
if (m_uploadURL.startsWith("http:")) {
URL redirectURL = getRedirectURL(m_uploadURL);
if (redirectURL != null) {
m_uploadURL = redirectURL.toString();
}
}
return m_uploadURL;
}
}
/**
* Get an HTTP resource with the response as an InputStream, given a
* resource locator that either begins with 'info:fedora/' , 'http://', or
* '/'. This method will follow redirects if FOLLOW_REDIRECTS is true. Note
* that if the HTTP response has no body, the InputStream will be empty. The
* success of a request can be checked with getResponseCode(). Usually
* you'll want to see a 200. See
* http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for other codes.
*
* @param locator
* A URL, relative Fedora URL, or Fedora URI that we want to do an
* HTTP GET upon
* @param failIfNotOK
* boolean value indicating if an exception should be thrown if we do
* NOT receive an HTTP 200 response (OK)
* @return HttpInputStream the HTTP response
* @throws IOException
*/
public HttpInputStream get(String locator, boolean failIfNotOK)
throws IOException {
return get(locator, failIfNotOK, FOLLOW_REDIRECTS);
}
/**
* Get an HTTP resource with the response as an InputStream, given a URL.
* This method will follow redirects if FOLLOW_REDIRECTS is true. Note that
* if the HTTP response has no body, the InputStream will be empty. The
* success of a request can be checked with getResponseCode(). Usually
* you'll want to see a 200. See
* http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for other codes.
*
* @param url
* A URL that we want to do an HTTP GET upon
* @param failIfNotOK
* boolean value indicating if an exception should be thrown if we do
* NOT receive an HTTP 200 response (OK)
* @return HttpInputStream the HTTP response
* @throws IOException
*/
public HttpInputStream get(URL url, boolean failIfNotOK) throws IOException {
return get(url, failIfNotOK, FOLLOW_REDIRECTS);
}
/**
* Get an HTTP resource with the response as an InputStream, given a
* resource locator that either begins with 'info:fedora/' , 'http://', or
* '/'. Note that if the HTTP response has no body, the InputStream will be
* empty. The success of a request can be checked with getResponseCode().
* Usually you'll want to see a 200. See
* http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for other codes.
*
* @param locator
* A URL, relative Fedora URL, or Fedora URI that we want to do an
* HTTP GET upon
* @param failIfNotOK
* boolean value indicating if an exception should be thrown if we do
* NOT receive an HTTP 200 response (OK)
* @param followRedirects
* boolean value indicating whether HTTP redirects should be handled
* in this method, or be passed along so that they can be handled
* later.
* @return HttpInputStream the HTTP response
* @throws IOException
*/
public HttpInputStream get(String locator,
boolean failIfNotOK,
boolean followRedirects) throws IOException {
// Convert the locator to a proper Fedora URL and the do a get.
String url = getLocatorAsURL(locator);
return get(new URL(url), failIfNotOK, followRedirects);
}
/**
* Get an HTTP resource with the response as an InputStream, given a URL.
* Note that if the HTTP response has no body, the InputStream will be
* empty. The success of a request can be checked with getResponseCode().
* Usually you'll want to see a 200. See
* http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for other codes.
*
* @param url
* A URL that we want to do an HTTP GET upon
* @param failIfNotOK
* boolean value indicating if an exception should be thrown if we do
* NOT receive an HTTP 200 response (OK)
* @param followRedirects
* boolean value indicating whether HTTP redirects should be handled
* in this method, or be passed along so that they can be handled
* later.
* @return HttpInputStream the HTTP response
* @throws IOException
*/
public HttpInputStream get(URL url,
boolean failIfNotOK,
boolean followRedirects) throws IOException {
String urlString = url.toString();
LOG.debug("FedoraClient is getting " + urlString);
HttpClient client = getHttpClient();
GetMethod getMethod = new GetMethod(urlString);
getMethod.setDoAuthentication(true);
getMethod.setFollowRedirects(followRedirects);
HttpInputStream in = new HttpInputStream(client, getMethod, urlString);
int status = in.getStatusCode();
if (failIfNotOK) {
if (status != 200) {
if (followRedirects && 300 <= status && status <= 399) {
// Handle the redirect here !
LOG
.debug("FedoraClient is handling redirect for HTTP STATUS="
+ status);
Header hLoc = in.getResponseHeader("location");
if (hLoc != null) {
LOG.debug("FedoraClient is trying redirect location: "
+ hLoc.getValue());
// Try the redirect location, but don't try to handle another level of redirection.
return get(hLoc.getValue(), true, false);
} else {
try {
throw new IOException("Request failed [" + status
+ " " + in.getStatusText() + "]");
} finally {
try {
in.close();
} catch (Exception e) {
LOG.error("Can't close InputStream: "
+ e.getMessage());
}
}
}
} else {
try {
throw new IOException("Request failed ["
+ in.getStatusCode() + " " + in.getStatusText()
+ "] : " + urlString);
} finally {
try {
in.close();
} catch (Exception e) {
LOG.error("Can't close InputStream: "
+ e.getMessage());
}
}
}
}
}
return in;
}
/**
* Get an HTTP resource with the response as a String instead of an
* InputStream, given a resource locator that either begins with
* 'info:fedora/' , 'http://', or '/'.
*
* @param locator
* A URL, relative Fedora URL, or Fedora URI that we want to do an
* HTTP GET upon
* @param failIfNotOK
* boolean value indicating if an exception should be thrown if we do
* NOT receive an HTTP 200 response (OK)
* @param followRedirects
* boolean value indicating whether HTTP redirects should be handled
* in this method, or be passed along so that they can be handled
* later.
* @return String the HTTP response as a string
* @throws IOException
*/
public String getResponseAsString(String locator,
boolean failIfNotOK,
boolean followRedirects)
throws IOException {
InputStream in = get(locator, failIfNotOK, followRedirects);
// Convert the response into a String.
try {
BufferedReader reader =
new BufferedReader(new InputStreamReader(in));
StringBuffer buffer = new StringBuffer();
String line = reader.readLine();
while (line != null) {
buffer.append(line + "\n");
line = reader.readLine();
}
return buffer.toString();
} finally {
try {
in.close();
} catch (Exception e) {
LOG.error("Can't close InputStream: " + e.getMessage());
}
}
}
private String getLocatorAsURL(String locator) throws IOException {
String url;
if (locator.startsWith(FEDORA_URI_PREFIX)) {
url =
m_baseURL + "get/"
+ locator.substring(FEDORA_URI_PREFIX.length());
} else if (locator.startsWith("http://")
|| locator.startsWith("https://")) {
url = locator;
} else if (locator.startsWith("/")) {
// assume it's for something within this Fedora server
while (locator.startsWith("/")) {
locator = locator.substring(1);
}
url = m_baseURL + locator;
} else {
throw new IOException("Bad locator (must start with '"
+ FEDORA_URI_PREFIX + "', 'http[s]://', or '/'");
}
return url;
}
/**
* Get a new SOAP stub for API-A. If the baseURL for this
* <code>FedoraClient</code> specifies "http", regular HTTP communication
* will be attempted first. If the server redirects this client to use HTTPS
* instead, the redirect will be followed and SSL will be used
* automatically.
*/
public FedoraAPIA getAPIA() throws ServiceException, IOException {
return (FedoraAPIA) getSOAPStub(m_accessEndpoint);
}
public URL getAPIAEndpointURL() throws IOException {
return m_accessEndpoint.getURL();
}
/**
* Get a new SOAP stub for API-M. If the baseURL for this
* <code>FedoraClient</code> specifies "http", regular HTTP communication
* will be attempted first. If the server redirects this client to use HTTPS
* instead, the redirect will be followed and SSL will be used
* automatically.
*/
public FedoraAPIM getAPIM() throws ServiceException, IOException {
return (FedoraAPIM) getSOAPStub(m_managementEndpoint);
}
public URL getAPIMEndpointURL() throws IOException {
return m_managementEndpoint.getURL();
}
/**
* Get the appropriate API-A/M stub, given a SOAPEndpoint.
*/
private Object getSOAPStub(SOAPEndpoint endpoint) throws ServiceException,
IOException {
URL url = endpoint.getURL();
String protocol = url.getProtocol();
String host = url.getHost();
int port = url.getPort();
//String path = url.getPath();
if (port == -1) {
port = url.getDefaultPort();
}
if (endpoint == m_accessEndpoint) {
APIAStubFactory.SOCKET_TIMEOUT_SECONDS = SOCKET_TIMEOUT_SECONDS;
return APIAStubFactory.getStubAltPath(protocol, host, port, url
.getPath(), m_user, m_pass);
} else if (endpoint == m_managementEndpoint) {
APIMStubFactory.SOCKET_TIMEOUT_SECONDS = SOCKET_TIMEOUT_SECONDS;
return APIMStubFactory.getStubAltPath(protocol, host, port, url
.getPath(), m_user, m_pass);
} else {
throw new IllegalArgumentException("Unrecognized endpoint: "
+ endpoint.getName());
}
}
public static String getVersion() {
ResourceBundle bundle =
ResourceBundle.getBundle("fedora.client.resources.Client");
return bundle.getString("version");
}
public static List<String> getCompatibleServerVersions() {
ResourceBundle bundle =
ResourceBundle.getBundle("fedora.client.resources.Client");
List<String> list = new ArrayList<String>();
String versions = bundle.getString("compatibleServerVersions");
if (versions != null && versions.trim().length() > 0) {
String[] va = versions.trim().split(" ");
for (String element : va) {
list.add(element);
}
}
String clientVersion = getVersion();
if (!list.contains(clientVersion)) {
list.add(getVersion());
}
return list;
}
/**
* Get the version reported by the remote Fedora server.
*/
public String getServerVersion() throws IOException {
// only do this once -- future invocations will use the known value
if (m_serverVersion == null) {
// Make the APIA call for describe repository
// and make sure that HTTP 302 status is handled.
String desc = getResponseAsString("/describe?xml=true", true, true);
LOG.debug("describeRepository response:\n" + desc);
String[] parts = desc.split("<repositoryVersion>");
if (parts.length < 2) {
throw new IOException("Could not find repositoryVersion element in content of /describe?xml=true");
}
int i = parts[1].indexOf("<");
if (i == -1) {
throw new IOException("Could not find end of repositoryVersion element in content of /describe?xml=true");
}
m_serverVersion = parts[1].substring(0, i).trim();
LOG.debug("Server version is " + m_serverVersion);
}
return m_serverVersion;
}
/**
* Return the current date as reported by the Fedora server.
*
* @throws IOException
* if the HTTP Date header is not provided by the server for any
* reason, or it is in the wrong format.
*/
public Date getServerDate() throws IOException {
HttpInputStream in = get("/describe", false, false);
String dateString = null;
try {
Header header = in.getResponseHeader("Date");
if (header == null) {
throw new IOException("Date was not supplied in HTTP response "
+ "header for " + m_baseURL + "describe");
}
dateString = header.getValue();
// This is the date format recommended by RFC2616
SimpleDateFormat format =
new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z",
Locale.US);
format.setTimeZone(TimeZone.getTimeZone("UTC"));
return format.parse(dateString);
} catch (ParseException e) {
throw new IOException("Unparsable date (" + dateString
+ ") in HTTP response header for " + m_baseURL + "describe");
} finally {
in.close();
}
}
public Date getLastModifiedDate(String locator) throws IOException {
if (locator.startsWith(FEDORA_URI_PREFIX)) {
String query =
"select $date " + "from <#ri> " + "where <" + locator
+ "> <" + VIEW.LAST_MODIFIED_DATE.uri + "> $date";
Map<String, String> map = new HashMap<String, String>();
map.put("lang", "itql");
map.put("query", query);
TupleIterator tuples = getTuples(map);
try {
if (tuples.hasNext()) {
Map<String, Node> row = tuples.next();
Literal dateLiteral = (Literal) row.get("date");
if (dateLiteral == null) {
throw new IOException("A row was returned, but it did not contain a 'date' binding");
}
return DateUtility.parseDateAsUTC(dateLiteral
.getLexicalForm());
} else {
throw new IOException("No rows were returned");
}
} catch (TrippiException e) {
throw new IOException(e.getMessage());
} finally {
try {
tuples.close();
} catch (Exception e) {
}
}
} else {
HttpClient client = getHttpClient();
HeadMethod head = new HeadMethod(locator);
head.setDoAuthentication(true);
head.setFollowRedirects(FOLLOW_REDIRECTS);
try {
int statusCode = client.executeMethod(head);
if (statusCode != HttpStatus.SC_OK) {
throw new IOException("Method failed: "
+ head.getStatusLine());
}
//Header[] headers = head.getResponseHeaders();
// Retrieve just the last modified header value.
Header header = head.getResponseHeader("last-modified");
if (header != null) {
String lastModified = header.getValue();
return DateUtility.convertStringToDate(lastModified);
} else {
// return current date time
return new Date();
}
} finally {
head.releaseConnection();
}
}
}
public void reloadPolicies() throws IOException {
InputStream in = null;
try {
in = get("/management/control?action=reloadPolicies", true, true);
} finally {
try {
in.close();
} catch (Exception e) {
LOG.error("Can't close InputStream: " + e.getMessage());
}
}
}
/**
* Get tuples from the remote resource index. The map contains
* <em>String</em> values for parameters that should be passed to the
* service. Two parameters are required: 1) lang 2) query Two parameters to
* the risearch service are implied: 1) type = tuples 2) format = sparql See
* http://www.fedora.info/download/2.0/userdocs/server/webservices/risearch/#app.tuples
*/
public TupleIterator getTuples(Map<String, String> params)
throws IOException {
params.put("type", "tuples");
params.put("format", RDFFormat.SPARQL.getName());
try {
String url = getRIQueryURL(params);
return TupleIterator.fromStream(get(url, true, true),
RDFFormat.SPARQL);
} catch (TrippiException e) {
throw new IOException("Error getting tuple iterator: "
+ e.getMessage());
}
}
private String getRIQueryURL(Map<String, String> params) throws IOException {
if (params.get("type") == null) {
throw new IOException("'type' parameter is required");
}
if (params.get("lang") == null) {
throw new IOException("'lang' parameter is required");
}
if (params.get("query") == null) {
throw new IOException("'query' parameter is required");
}
if (params.get("format") == null) {
throw new IOException("'format' parameter is required");
}
return m_baseURL + "risearch?" + encodeParameters(params);
}
private String encodeParameters(Map<String, String> params) {
StringBuffer encoded = new StringBuffer();
Iterator<String> iter = params.keySet().iterator();
int n = 0;
while (iter.hasNext()) {
String name = iter.next();
if (n > 0) {
encoded.append("&");
}
n++;
encoded.append(name);
encoded.append('=');
try {
encoded.append(URLEncoder.encode(params.get(name), "UTF-8"));
} catch (UnsupportedEncodingException e) { // UTF-8 won't fail
}
}
return encoded.toString();
}
/**
* Ping the given endpoint to see if an HTTP 302 status code is returned. If
* so, return the location given in the HTTP response header. If not, return
* null.
*/
private URL getRedirectURL(String location) throws IOException {
HttpInputStream in = get(location, false, false);
try {
if (in.getStatusCode() == 302) {
Header h = in.getResponseHeader("location");
if (h != null) {
return new URL(h.getValue());
}
}
return null;
} finally {
try {
in.close();
} catch (Exception e) {
}
}
}
/**
* Class for storing a Fedora SOAP endpoint, which consists of an endpoint
* name and a URL. The endpoint name is provided to the constructor. The URL
* is determined automatically, once, based on:
* <ul>
* <li> The baseURL provided to the FedoraClient instance.</li>
* <li> The server version.</li>
* <li> Whether the server automatically redirects non-SSL SOAP requests to
* an SSL endpoint.</li>
* </ul>
*/
public class SOAPEndpoint {
String m_name;
URL m_url;
public SOAPEndpoint(String name) {
m_name = name;
}
public String getName() {
return m_name;
}
public URL getURL() throws IOException {
// only do this once -- future invocations will use the saved value.
if (m_url == null) {
// The endpoint URL has not been determined yet.
// It will be determined in the following manner:
//
// If the Fedora server version is 2.0:
// url = (baseURL)/(endpointName)/soap
// Otherwise, the Fedora server version must be 2.1+:
// If (baseURL) specifies "http":
// Hit (baseURL)/services/(endpointName).
// If it redirects:
// url = (redirectURL)
// Otherwise:
// url = (baseURL)/services/(endpointName)
// Otherwise:
// url = (baseURL)/services/(endpointName)
//
if (getServerVersion().equals("2.0")) {
m_url = new URL(m_baseURL + m_name + "/soap");
} else {
if (m_baseURL.startsWith("http:")) {
m_url = getRedirectURL("/services/" + m_name);
}
if (m_url == null) {
m_url = new URL(m_baseURL + "services/" + m_name);
}
}
}
return m_url;
}
}
}