### *** This interface provides Binary Compatibility only, not Source Compatibility ***

Package com.sas.services.publish.webdav

# Interface DAVTransportInterface

All Superinterfaces:
  `TransportInterface`

@SASScope("ALL") @BinaryCompatibilityOnly public interface DAVTransportInterface extends TransportInterface
The DAVTransportInterface provides a mechanism for publishing a result package to a WebDAV server, and for retrieving a result package from a WebDAV server.

WebDAV (Web-based Distributed Authoring and Versioning) is an emerging industry standard that is based on extensions to HTTP 1.1 that enables collaborative development of files and collections of files on remote Web servers. WebDAV is documented in RFC2518. Visit the WebDAV site for more information.

## Publishing the Result Package as an Archive

By default, when a result package is published to a WebDAV server, the result package is published as a set of loose files. This default behavior can be overridden by using the `asArchive(boolean)` method. If set to `true`, the result package will be published to the WebDAV server as an archive (.spk file). See WebDAV Publish as Archive Example for an example of publishing an archive to a WebDAV server.

The WebDAV transport also supports the retrieval of these binary result packages from a WebDAV server. See WebDAV Retrieve Archive Example for an example of retrieving an archive from a WebDAV server.

## Namespace Usage

Namespaces can be defined on the WebDAV transport, using the `setNamespaces(java.util.Map)` method. The namespace is specified as a map. The key identifies the prefix and the value identifies the namespace URI.

The WebDAV transport supports namespaces when publishing or retrieving a result package. Namespaces are unique names that associate published packages with specific contexts on a WebDAV-compliant server. The association of a namespace with a package organizes package data on a server according to meaningful criteria, or contexts. A namespace is an additional scoping criterion for a name/value description of a package or package entry.

### Namespace Usage When Publishing A Result Package

If namespaces are set on the WebDAV delivery transport that is used to publish a result package, the namespace name/value descriptors are stored with the result package or its entries to the specified WebDAV namespace. As an example, a package might be described as containing first quarter profits that were generated by the Houston office. The specified description and scope uniquely define the package so that consumers can filter name/value pairs on packages or entries unambiguously. An example of a namespace definition follows:

      Map m = new HashMap();
      m.put("HOUSTON", "http://www.AlphaliteAirways.com/revenue.final");

To define specific name/value pairs to the namespace, the name should be preceded by the namespace prefix, and then a colon. For example:

       AttributeMapInterface namevalues = new AttributeMap();
       namevalues.addAttribute("HOUSTON:type", "quarterlyReport");

See WebDAV Publishing with Namespaces Example for an example of using namespaces when publishing a result package to a WebDAV server.

### Namespace Usage When Retrieving A Result Package

If namespaces are set on the WebDAV delivery transport that is used to retrieve a result package, the namespaces identify what namespaces that you are interested in returning. Only empty namespaces, and those that match the specified namespaces, will be returned.

As an example, if the calling application is only interested in information containing profit information, I must define the namespaces of interest:

     Map m = new HashMap();
     m.put("a", "http://www.AlphaliteAirways.com/revenue.final");
     m.put("b", "http://www.AlphaliteAirways.com/revenue.first");

This identifies two additional namespaces of interests. Only those name/value pairs that match these namespaces, or the emptly namespace, will be returned. Name/value pairs that are defined to one of the namespaces will be identified by prepending the name with the namespace prefix, and then a colon. For example, if the name/value pair, type=quarterlyReport was defined to the "http://www.AlphaliteAirways.com/revenue.final" namespace, its name will be returned as "a:type" and its value will be "quarterlyReport"

See WebDAV Retrieving with Namespaces Example for an example of using namespaces when retrieving a result package from a WebDAV server.

See Also:
  - `TransportFactory`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `COLLECTION_URL`
  The URL to which the result package will be published.
  `static final int`
  `NOREPLACE`
  If the collection already exists, do not publish.
  `static final int`
  `PARENT_URL`
  The URL under which the result package will be published.
  `static final int`
  `REPLACE`
  If the collection already exists, replace it by deleting the current collection and its entities first.
  `static final int`
  `UPDATE`
  If the collection already exists, update the existing collection by replacing like-named entities and adding newly named entities.
  `static final int`
  `UPDATEANY`
  If the collection already exists, update the existing collection by replacing like-named entities and adding newly named entities.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `asArchive(boolean publishAsArchive)`
  Determines if the package will be published to a collection as a set of loose files or if the package will be published as a binary archive (.spk) file.
  `String`
  `getArchiveName()`
  If publishing the package as an archive to the webDAV server, this identifies the archive filename.
  `int`
  `getCreationMode()`
  Returns the creation mode.
  `String`
  `getDomain()`
  Returns the authentication domain.
  `Map`
  `getNamespaces()`
  Returns the namespaces.
  `String`
  `getPassword()`
  Returns the HTTP password used when binding to the webDAV server.
  `String`
  `getProxyURL()`
  Returns the URL of the proxy server.
  `String`
  `getURL()`
  Returns the collection URL.
  `int`
  `getURLRole()`
  Returns the role of the URL.
  `String`
  `getUserName()`
  Returns the HTTP user name used when binding to the webDAV server.
  `void`
  `setArchiveName(String name)`
  If publishing the package as an archive to the webDAV server, this identifies the archive filename.
  `void`
  `setCreationMode(int mode)`
  Sets the creation mode that determines how the package will be published to the WebDAV server.
  `void`
  `setNamespaces(Map namespaces)`
  Sets the namespaces to be used when publishing or retrieving a result package or when creating the SASPackage event.
  `void`
  `setPassword(String password)`
  Set the HTTP password to use when binding to the webDAV server.
  `void`
  `setProxyURL(String proxyUrl)`
  Sets the URL of the proxy server to be used when publishing or retrieving a result package using the WebDAV delivery transport.
  `void`
  `setURLRole(int role)`
  Sets the role of the URL.
  `void`
  `setUserName(String userName)`
  Set the HTTP user name to use when binding to the webDAV server.

  ### Methods inherited from interface com.sas.services.publish.TransportInterface

  `getLogger, getResultPackage, getSessionContext, publishResultPackage, setLogger`

- ## Field Details

  - ### COLLECTION_URL

    static final int COLLECTION_URL
    The URL to which the result package will be published. The URL explicitly defines the name of the collection to which the package is published.
    See Also:
      - Constant Field Values

  - ### PARENT_URL

    static final int PARENT_URL
    The URL under which the result package will be published. The collection name is automatically generated.
    See Also:
      - Constant Field Values

  - ### REPLACE

    static final int REPLACE
    If the collection already exists, replace it by deleting the current collection and its entities first.
    See Also:
      - Constant Field Values

  - ### NOREPLACE

    static final int NOREPLACE
    If the collection already exists, do not publish.
    See Also:
      - Constant Field Values

  - ### UPDATE

    static final int UPDATE
    If the collection already exists, update the existing collection by replacing like-named entities and adding newly named entities. The publish will fail if the existing collection is not a SAS package.
    See Also:
      - Constant Field Values

  - ### UPDATEANY

    static final int UPDATEANY
    If the collection already exists, update the existing collection by replacing like-named entities and adding newly named entities. The existing collection will be updated even if it is not SAS package collection. A consequence of using UPDATEANY is that SAS may be unable to retrieve certain resources within the SAS package collection.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getUserName

    String getUserName()
    Returns the HTTP user name used when binding to the webDAV server.
    Returns:
      `String` The user name explicitly set on the constructor or on the `setUserName(java.lang.String)` method. This username may be `null` if not previously set.

  - ### setUserName

    void setUserName(String userName)
    Set the HTTP user name to use when binding to the webDAV server. This will override the user context's bind credentials.
    Parameters:
      `userName` - The user name.

  - ### setPassword

    void setPassword(String password)
    Set the HTTP password to use when binding to the webDAV server.
    Parameters:
      `password` - The password.

  - ### getPassword

    String getPassword()
    Returns the HTTP password used when binding to the webDAV server.
    Returns:
      `String` The HTTP password explicitly set on the constructor or on the `setPassword(java.lang.String)` method. This password may be `null` if not previously set.

  - ### getURL

    String getURL()
    Returns the collection URL.
    Returns:
      `String` The collection URL.

  - ### getDomain

    String getDomain()
    Returns the authentication domain.
    Returns:
      `String` The authentication domain; may be `null` if not previously set.

  - ### getNamespaces

    Map getNamespaces()
    Returns the namespaces. Namespaces are unique names that associated published packages with specific contexts on a WebDAV-compliant server. The association of a namespace with a package organizes package data on a server according to meaningful criteria, or contexts. A namespace is an additional scoping criterion for a name/value description of a package or package entry. See Namespace Usage for more details on namespaces.
    Returns:
      `Map` The namespaces which map a prefix to a namespace. The key identifies the prefix to associate with a given namespace URI. This may be `null`.

  - ### setNamespaces

    void setNamespaces(Map namespaces) throws IllegalArgumentException
    Sets the namespaces to be used when publishing or retrieving a result package or when creating the SASPackage event. See Namespace Usage for more details on namespaces.
    Parameters:
      `namespaces` - The namespaces. The namespace specification is case-sensitive.
    Throws:
      `IllegalArgumentException` - If an invalid namespace is specified.

  - ### getProxyURL

    String getProxyURL()
    Returns the URL of the proxy server.
    Returns:
      `String` The URL of the proxy server. This may be `null`.

  - ### setProxyURL

    void setProxyURL(String proxyUrl)
    Sets the URL of the proxy server to be used when publishing or retrieving a result package using the WebDAV delivery transport.
    Parameters:
      `proxyUrl` - The URL of the proxy server.

  - ### getURLRole

    int getURLRole()
    Returns the role of the URL. The URL is defined when the WebDAV transport is instantiated using `TransportFactory`. Supported roles include `COLLECTION_URL` and `PARENT_URL`.
    Returns:
      `String` The URL of the proxy server.

  - ### setURLRole

    void setURLRole(int role) throws IllegalArgumentException
    Sets the role of the URL. The URL is defined when the WebDAV transport is instantiated using `TransportFactory`. The role defaults to `COLLECTION_URL`. This default role can be overridden by using this method to explicitly set the role to `PARENT_URL`.

    The role of the URL is used when the result package is published to a WebDAV server. If a collection role is specified, the URL identifies the name of the result package collection. If a parent role is specified, the URL identifies the collection under which the result package will be published. A unique collection name will be created by the WebDAV transport and the result package will be published to that collection.

    If publishing the result package as an archive (by invoking the `asArchive(boolean)` method, the URL role is ignored. The specified URL will always be used as a parent URL; that is, the archive will be created as a resource in the specified URL.

    When retrieving a result package from a WebDAV server, the role is ignored because the URL must identify the collection that is the result package.

    Parameters:
      `role` - The role of the URL. Supported roles include `COLLECTION_URL` and `PARENT_URL`.
    Throws:
      `IllegalArgumentException` - If an invalid role is specified.

  - ### asArchive

    void asArchive(boolean publishAsArchive)
    Determines if the package will be published to a collection as a set of loose files or if the package will be published as a binary archive (.spk) file. The default behavior is to publish the result package as a set of loose files. This default behavior can be overridden by specifying `true` on this method. This will cause the result package to be published as an archive (.spk file)

    The name of the archive file can be specified on the `setArchiveName(String)` method. If an archive name is not specified, a unique name will be generated.

    If asArchive is set to `true`, the URL role will be ignored. The specified URL will always be used as a parent URL; that is, the archive will be created as a resource in the specified URL.

    Parameters:
      `publishAsArchive` - `true` if the package should be published as an archive file (.spk) to the WebDAV server; `false` if the package should be published as loose files.

  - ### setArchiveName

    void setArchiveName(String name)
    If publishing the package as an archive to the webDAV server, this identifies the archive filename. The name should not include the .spk extension; this will be added by the underlying webdav transport. If a name is not specified, a unique filename will be generated.
    Parameters:
      `name` - The archive filename; this name should not include the .spk extension.

  - ### getArchiveName

    String getArchiveName()
    If publishing the package as an archive to the webDAV server, this identifies the archive filename. The name should not include the .spk extension; this will be added by the underlying webdav transport. If a name is not specified, a unique filename will be generated.
    Returns:
      `String` The archive filename; this may be `null` if not previously set using `setArchiveName`

  - ### getCreationMode

    int getCreationMode()
    Returns the creation mode. The default behavior is `REPLACE`.
    Returns:
      `int` The creation mode. Supported modes include `REPLACE`, `NOREPLACE`, `UPDATE` and `UPDATEANY`.

  - ### setCreationMode

    void setCreationMode(int mode) throws IllegalArgumentException
    Sets the creation mode that determines how the package will be published to the WebDAV server. The default behavior is `REPLACE`.
    Parameters:
      `mode` - The creation mode. Supported modes include `REPLACE`, `NOREPLACE`, `UPDATE` and `UPDATEANY`.
    Throws:
      `IllegalArgumentException` - If an invalid mode is specified.