com.github.sardine

Interface Sardine

All Known Implementing Classes:

SardineImpl

public interface Sardine

The main interface for Sardine operations.

Author:

jonstevens

Method Summary

Modifier and Type	Method and Description
void	copy(String sourceUrl, String destinationUrl) Copy a url from source to destination using WebDAV COPY.
void	copy(String sourceUrl, String destinationUrl, boolean overwrite) Copy a url from source to destination using WebDAV COPY.
void	createDirectory(String url) Uses WebDAV MKCOL to create a directory at the specified url
void	delete(String url) Delete a resource using HTTP DELETE at the specified url
void	disableCompression() Disables support for HTTP compression.
void	disablePreemptiveAuthentication() Disable preemptive authentication.
void	enableCompression() Enables HTTP GZIP compression.
void	enablePreemptiveAuthentication(String hostname) Send a Basic authentication header with each request even before 401 is returned.
void	enablePreemptiveAuthentication(String hostname, int httpPort, int httpsPort) Send a Basic authentication header with each request even before 401 is returned.
void	enablePreemptiveAuthentication(URL url) Send a Basic authentication header with each request even before 401 is returned.
boolean	exists(String url) Performs a HTTP HEAD request to see if a resource exists or not.
InputStream	get(String url) Uses HTTP GET to download data from a server.
InputStream	get(String url, Map<String,String> headers) Uses HTTP GET to download data from a server.
DavAcl	getAcl(String url) Read access control list for resource
List<String>	getPrincipalCollectionSet(String url) The principals that are available on the server that implements this resource.
List<DavPrincipal>	getPrincipals(String url) List the principals that can be used to set ACLs on given url
DavQuota	getQuota(String url) Read quota properties for resource
List<DavResource>	getResources(String url) Deprecated.
void	ignoreCookies() Ignores cookies.
List<DavResource>	list(String url) Gets a directory listing using WebDAV PROPFIND.
List<DavResource>	list(String url, int depth) Gets a directory listing using WebDAV PROPFIND.
List<DavResource>	list(String url, int depth, boolean allProp) Gets a directory listing using WebDAV PROPFIND.
List<DavResource>	list(String url, int depth, Set<QName> props) Gets a directory listing using WebDAV PROPFIND.
String	lock(String url) Put an exclusive write lock on this resource.
void	move(String sourceUrl, String destinationUrl) Move a url to from source to destination using WebDAV MOVE.
void	move(String sourceUrl, String destinationUrl, boolean overwrite) Move a url to from source to destination using WebDAV MOVE.
List<DavResource>	patch(String url, List<Element> addProps, List<QName> removeProps) Add or remove custom properties for a url using WebDAV PROPPATCH.
List<DavResource>	patch(String url, Map<QName,String> addProps) Add custom properties for a url WebDAV PROPPATCH.
List<DavResource>	patch(String url, Map<QName,String> addProps, List<QName> removeProps) Add or remove custom properties for a url using WebDAV PROPPATCH.
List<DavResource>	propfind(String url, int depth, Set<QName> props) Fetches a resource using WebDAV PROPFIND.
void	put(String url, byte[] data) Uses HTTP PUT to send data to a server.
void	put(String url, byte[] data, String contentType) Uses PUT to send data to a server with a specific content type header.
void	put(String url, File localFile, String contentType) Uses PUT to upload file to a server with specific contentType.
void	put(String url, File localFile, String contentType, boolean expectContinue) Uses PUT to upload file to a server with specific contentType.
void	put(String url, InputStream dataStream) Uses PUT to send data to a server.
void	put(String url, InputStream dataStream, Map<String,String> headers) Uses PUT to send data to a server with specific headers.
void	put(String url, InputStream dataStream, String contentType) Uses PUT to send data to a server with a specific content type header.
void	put(String url, InputStream dataStream, String contentType, boolean expectContinue) Uses PUT to send data to a server with a specific content type header.
void	put(String url, InputStream dataStream, String contentType, boolean expectContinue, long contentLength) Uses PUT to send data to a server with a specific content type header.
String	refreshLock(String url, String token, String file) A LOCK request with no request body is a "LOCK refresh" request.
<T> T	report(String url, int depth, SardineReport<T> report) Runs a report on the given resource using WebDAV REPORT.
List<DavResource>	search(String url, String language, String query) Perform a search of the Webdav repository.
void	setAcl(String url, List<DavAce> aces) Write access control list for resource
void	setCredentials(String username, String password) Add credentials to any scope.
void	setCredentials(String username, String password, String domain, String workstation)
void	setCustomProps(String url, Map<String,String> addProps, List<String> removeProps) Deprecated.
void	shutdown() Releasing any resources that might be held open.
void	unlock(String url, String token) Unlock the resource.

Method Detail

setCredentials

void setCredentials(String username,
                    String password)

Add credentials to any scope.

Parameters:

username - Use in authentication header credentials

password - Use in authentication header credentials

setCredentials

void setCredentials(String username,
                    String password,
                    String domain,
                    String workstation)

Parameters:

username - Use in authentication header credentials

password - Use in authentication header credentials

domain - NTLM authentication

workstation - NTLM authentication

getResources

@Deprecated
List<DavResource> getResources(String url)
                                    throws IOException

Deprecated.

Throws:

IOException

See Also:

list(String)

list

List<DavResource> list(String url)
                throws IOException

Gets a directory listing using WebDAV PROPFIND.

Parameters:

url - Path to the resource including protocol and hostname

Returns:

List of resources for this URI including the parent resource itself

Throws:

IOException - I/O error or HTTP response validation failure

list

List<DavResource> list(String url,
                       int depth)
                throws IOException

Gets a directory listing using WebDAV PROPFIND.

Parameters:

url - Path to the resource including protocol and hostname

depth - The depth to look at (use 0 for single resource, 1 for directory listing, -1 for infinite recursion)

Returns:

List of resources for this URI including the parent resource itself

Throws:

IOException - I/O error or HTTP response validation failure

list

List<DavResource> list(String url,
                       int depth,
                       Set<QName> props)
                throws IOException

Gets a directory listing using WebDAV PROPFIND.

Parameters:

url - Path to the resource including protocol and hostname

depth - The depth to look at (use 0 for single resource, 1 for directory listing, -1 for infinite recursion)

props - Additional properties which should be requested.

Returns:

List of resources for this URI including the parent resource itself

Throws:

IOException - I/O error or HTTP response validation failure

list

List<DavResource> list(String url,
                       int depth,
                       boolean allProp)
                throws IOException

Gets a directory listing using WebDAV PROPFIND.

Parameters:

url - Path to the resource including protocol and hostname

depth - The depth to look at (use 0 for single resource, 1 for directory listing, -1 for infinite recursion)

allProp - If allprop should be used, which can be inefficient sometimes; warning: no allprop does not retrieve custom props, just the basic ones

Returns:

List of resources for this URI including the parent resource itself

Throws:

IOException - I/O error or HTTP response validation failure

propfind

List<DavResource> propfind(String url,
                           int depth,
                           Set<QName> props)
                    throws IOException

Fetches a resource using WebDAV PROPFIND. Only the specified properties are retrieved.

Parameters:

url - Path to the resource including protocol and hostname

depth - The depth to look at (use 0 for single resource, 1 for directory listing, -1 for infinite recursion)

props - Set of properties to be requested

Returns:

List of resources for this URI including the parent resource itself

Throws:

IOException - I/O error or HTTP response validation failure

report

<T> T report(String url,
             int depth,
             SardineReport<T> report)
      throws IOException

Runs a report on the given resource using WebDAV REPORT.

Parameters:

url - Path to the resource including protocol and hostname

depth - The depth to look at (use 0 for single resource, 1 for directory listing, -1 for infinite recursion)

report - The report to run

Returns:

Result of the report, packaged in a report-specific result object

Throws:

IOException - I/O error or HTTP response validation failure

search

List<DavResource> search(String url,
                         String language,
                         String query)
                  throws IOException

Perform a search of the Webdav repository.

Parameters:

url - The base resource to search from.

language - The language the query is formed in.

query - The query string to be processed by the webdav server.

Returns:

A list of matching resources.

Throws:

IOException - I/O error or HTTP response validation failure.

setCustomProps

@Deprecated
void setCustomProps(String url,
                                Map<String,String> addProps,
                                List<String> removeProps)
                         throws IOException

Deprecated.

Throws:

IOException

See Also:

patch(String, java.util.Map, java.util.List)

patch

List<DavResource> patch(String url,
                        Map<QName,String> addProps)
                 throws IOException

Add custom properties for a url WebDAV PROPPATCH.

Parameters:

url - Path to the resource including protocol and hostname

addProps - Properties to add to resource. If a property already exists then its value is replaced.

Returns:

The patched resources from the response

Throws:

IOException - I/O error or HTTP response validation failure

patch

List<DavResource> patch(String url,
                        Map<QName,String> addProps,
                        List<QName> removeProps)
                 throws IOException

Add or remove custom properties for a url using WebDAV PROPPATCH.

Parameters:

url - Path to the resource including protocol and hostname

addProps - Properties to add to resource. If a property already exists then its value is replaced.

removeProps - Properties to remove from resource. Specifying the removal of a property that does not exist is not an error.

Returns:

The patched resources from the response

Throws:

IOException - I/O error or HTTP response validation failure

patch

List<DavResource> patch(String url,
                        List<Element> addProps,
                        List<QName> removeProps)
                 throws IOException

Add or remove custom properties for a url using WebDAV PROPPATCH.

Parameters:

url - Path to the resource including protocol and hostname

addProps - Properties to add to resource. If a property already exists then its value is replaced.

removeProps - Properties to remove from resource. Specifying the removal of a property that does not exist is not an error.

Returns:

The patched resources from the response

Throws:

IOException - I/O error or HTTP response validation failure

get

InputStream get(String url)
         throws IOException

Uses HTTP GET to download data from a server. The stream must be closed after reading.

Parameters:

url - Path to the resource including protocol and hostname

Returns:

Data stream to read from

Throws:

IOException - I/O error or HTTP response validation failure

get

InputStream get(String url,
                Map<String,String> headers)
         throws IOException

Uses HTTP GET to download data from a server. The stream must be closed after reading.

Parameters:

url - Path to the resource including protocol and hostname

headers - Additional HTTP headers to add to the request

Returns:

Data stream to read from

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         byte[] data)
  throws IOException

Uses HTTP PUT to send data to a server. Repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

data - Input source

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         InputStream dataStream)
  throws IOException

Uses PUT to send data to a server. Not repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

dataStream - Input source

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         byte[] data,
         String contentType)
  throws IOException

Uses PUT to send data to a server with a specific content type header. Repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

data - Input source

contentType - MIME type to add to the HTTP request header

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         InputStream dataStream,
         String contentType)
  throws IOException

Uses PUT to send data to a server with a specific content type header. Not repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

dataStream - Input source

contentType - MIME type to add to the HTTP request header

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         InputStream dataStream,
         String contentType,
         boolean expectContinue)
  throws IOException

Uses PUT to send data to a server with a specific content type header. Not repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

dataStream - Input source

contentType - MIME type to add to the HTTP request header

expectContinue - Enable Expect: continue header for PUT requests.

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         InputStream dataStream,
         String contentType,
         boolean expectContinue,
         long contentLength)
  throws IOException

Uses PUT to send data to a server with a specific content type header. Not repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

dataStream - Input source

contentType - MIME type to add to the HTTP request header

expectContinue - Enable Expect: continue header for PUT requests.

contentLength - data size in bytes to set to Content-Length header

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         InputStream dataStream,
         Map<String,String> headers)
  throws IOException

Uses PUT to send data to a server with specific headers. Not repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

dataStream - Input source

headers - Additional HTTP headers to add to the request

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         File localFile,
         String contentType)
  throws IOException

Uses PUT to upload file to a server with specific contentType. Repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

localFile - local file to send

contentType - MIME type to add to the HTTP request header

Throws:

IOException - I/O error or HTTP response validation failure

put

void put(String url,
         File localFile,
         String contentType,
         boolean expectContinue)
  throws IOException

Uses PUT to upload file to a server with specific contentType. Repeatable on authentication failure.

Parameters:

url - Path to the resource including protocol and hostname

localFile - local file to send

contentType - MIME type to add to the HTTP request header

expectContinue - Enable Expect: continue header for PUT requests.

Throws:

IOException - I/O error or HTTP response validation failure

delete

void delete(String url)
     throws IOException

Delete a resource using HTTP DELETE at the specified url

Parameters:

url - Path to the resource including protocol and hostname

Throws:

IOException - I/O error or HTTP response validation failure

createDirectory

void createDirectory(String url)
              throws IOException

Uses WebDAV MKCOL to create a directory at the specified url

Parameters:

url - Path to the resource including protocol and hostname

Throws:

IOException - I/O error or HTTP response validation failure

move

void move(String sourceUrl,
          String destinationUrl)
   throws IOException

Move a url to from source to destination using WebDAV MOVE. Assumes overwrite.

Parameters:

sourceUrl - Path to the resource including protocol and hostname

destinationUrl - Path to the resource including protocol and hostname

Throws:

IOException - I/O error or HTTP response validation failure

move

void move(String sourceUrl,
          String destinationUrl,
          boolean overwrite)
   throws IOException

Move a url to from source to destination using WebDAV MOVE.

Parameters:

sourceUrl - Path to the resource including protocol and hostname

destinationUrl - Path to the resource including protocol and hostname

overwrite - true to overwrite if the destination exists, false otherwise.

Throws:

IOException - I/O error or HTTP response validation failure

copy

void copy(String sourceUrl,
          String destinationUrl)
   throws IOException

Copy a url from source to destination using WebDAV COPY. Assumes overwrite.

Parameters:

sourceUrl - Path to the resource including protocol and hostname

destinationUrl - Path to the resource including protocol and hostname

Throws:

IOException - I/O error or HTTP response validation failure

copy

void copy(String sourceUrl,
          String destinationUrl,
          boolean overwrite)
   throws IOException

Copy a url from source to destination using WebDAV COPY.

Parameters:

sourceUrl - Path to the resource including protocol and hostname

destinationUrl - Path to the resource including protocol and hostname

overwrite - true to overwrite if the destination exists, false otherwise.

Throws:

IOException - I/O error or HTTP response validation failure

exists

boolean exists(String url)
        throws IOException

Performs a HTTP HEAD request to see if a resource exists or not.

Parameters:

url - Path to the resource including protocol and hostname

Returns:

Anything outside of the 200-299 response code range returns false.

Throws:

IOException - I/O error or HTTP response validation failure

lock

String lock(String url)
     throws IOException

Put an exclusive write lock on this resource. A write lock must prevent a principal without the lock from successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, DELETE, or MKCOL on the locked resource. All other current methods, GET in particular, function independently of the lock.

A WebDAV compliant server is not required to support locking in any form. If the server does support locking it may choose to support any combination of exclusive and shared locks for any access types.

Parameters:

url - Path to the resource including protocol and hostname

Returns:

The lock token to unlock this resource. A lock token is a type of state token, represented as a URI, which identifies a particular lock. A lock token is returned by every successful LOCK operation in the lockdiscovery property in the response body, and can also be found through lock discovery on a resource.

Throws:

IOException - I/O error or HTTP response validation failure

refreshLock

String refreshLock(String url,
                   String token,
                   String file)
            throws IOException

A LOCK request with no request body is a "LOCK refresh" request. It's purpose is to restart all timers associated with a lock. The request MUST include an "If" header that contains the lock tokens of the locks to be refreshed (note there may be multiple in the case of shared locks).

Parameters:

url - Path to the resource including protocol and hostname

token - The lock token used to lock the resource

file - The name of the file at the end of the url

Returns:

The lock token to unlock this resource. A lock token is a type of state token, represented as a URI, which identifies a particular lock. A lock token is returned by every successful LOCK operation in the lockdiscovery property in the response body, and can also be found through lock discovery on a resource.

Throws:

IOException - I/O error or HTTP response validation failure

unlock

void unlock(String url,
            String token)
     throws IOException

Unlock the resource.

A WebDAV compliant server is not required to support locking in any form. If the server does support locking it may choose to support any combination of exclusive and shared locks for any access types.

Parameters:

url - Path to the resource including protocol and hostname

token - The lock token to unlock this resource.

Throws:

IOException - I/O error or HTTP response validation failure

See Also:

lock(String)

getAcl

DavAcl getAcl(String url)
       throws IOException

Read access control list for resource

Parameters:

url - Path to the resource including protocol and hostname

Returns:

Current ACL set on the resource

Throws:

IOException - I/O error or HTTP response validation failure

getQuota

DavQuota getQuota(String url)
           throws IOException

Read quota properties for resource

Parameters:

url - Path to the resource including protocol and hostname

Returns:

Current Quota and Size Properties for resource

Throws:

IOException - I/O error or HTTP response validation failure

setAcl

void setAcl(String url,
            List<DavAce> aces)
     throws IOException

Write access control list for resource

Parameters:

url - Path to the resource including protocol and hostname

aces - Access control elements

Throws:

IOException - I/O error or HTTP response validation failure

getPrincipals

List<DavPrincipal> getPrincipals(String url)
                          throws IOException

List the principals that can be used to set ACLs on given url

Parameters:

url - Path to the resource including protocol and hostname

Returns:

List of principals (in the form of urls according to spec)

Throws:

IOException - I/O error or HTTP response validation failure

getPrincipalCollectionSet

List<String> getPrincipalCollectionSet(String url)
                                throws IOException

The principals that are available on the server that implements this resource.

Parameters:

url - Path to the resource including protocol and hostname

Returns:

The URLs in DAV:principal-collection-set

Throws:

IOException - I/O error or HTTP response validation failure

enableCompression

void enableCompression()

Enables HTTP GZIP compression. If enabled, requests originating from Sardine will include "gzip" as an "Accept-Encoding" header.

If the server also supports gzip compression, it should serve the contents in compressed gzip format and include "gzip" as the Content-Encoding. If the content encoding is present, Sardine will automatically decompress the files upon reception.

disableCompression

void disableCompression()

Disables support for HTTP compression.

See Also:

enableCompression()

ignoreCookies

void ignoreCookies()

Ignores cookies.

enablePreemptiveAuthentication

void enablePreemptiveAuthentication(String hostname)

Send a Basic authentication header with each request even before 401 is returned. Uses default ports: 80 for http and 443 for https

Parameters:

hostname - The hostname to enable preemptive authentication for.

enablePreemptiveAuthentication

void enablePreemptiveAuthentication(URL url)

Send a Basic authentication header with each request even before 401 is returned.

Parameters:

url - The hostname, protocol and port to enable preemptive authentication for.

enablePreemptiveAuthentication

void enablePreemptiveAuthentication(String hostname,
                                    int httpPort,
                                    int httpsPort)

Send a Basic authentication header with each request even before 401 is returned.

Parameters:

hostname - The hostname to enable preemptive authentication for.

httpPort - The http port to enable preemptive authentication for. -1 for default value.

httpsPort - The https port to enable preemptive authentication for. -1 for default value.

disablePreemptiveAuthentication

void disablePreemptiveAuthentication()

Disable preemptive authentication.

shutdown

void shutdown()
       throws IOException

Releasing any resources that might be held open. This is an optional method, and callers are not expected to call it, but can if they want to explicitly release any open resources. Once a client has been shutdown, it should not be used to make any more requests.

Throws:

IOException