*** 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:

  • 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:

    • 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:

    • REPLACE

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

    • NOREPLACE

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

    • 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:

    • 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:

  • 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.