Interface SOAPRequest

  • All Known Subinterfaces:
    SOAPQueryJobResult, SOAPRemoteJob

    public interface SOAPRequest
    A SOAP request over HTTP. This contains a basic HTTP and SOAP client. Limitations:
    • There is only limited support for namespaces. The namespaces are retrieved from the XML document, if the same prefix is used for different URI's only the last definition is valid. This also applies to the default namespace.
    • Field Detail

      • REDWOOD_NOCREDENTIAL

        @Deprecated
        static final String REDWOOD_NOCREDENTIAL
        Deprecated.
        Special username to use to prevent credential from to overriding the Authorization header, the credential will be looked up (for licensing) but not used. This is obsolete as the licensing no longer counts SOAP endpoints.
        See Also:
        Constant Field Values
      • REJECTED_CIPHERSUITES_9_0_21

        @Deprecated
        static final String REJECTED_CIPHERSUITES_9_0_21
        Deprecated.
        The list of cipher suite patterns that was rejected by default in Cronacle 9.0.22.3 and below. No longer used.
        See Also:
        Constant Field Values
      • REJECTED_CIPHERSUITES_DEFAULT

        @Deprecated
        static final String REJECTED_CIPHERSUITES_DEFAULT
        Deprecated.
        The list of cipher suite patterns that are rejected by default in Cronacle 9.0.22.3 and later. No longer used.
        See Also:
        Constant Field Values
    • Method Detail

      • setRequest

        void setRequest​(String newRequest)
        Set the XML content of the SOAP request.
        Parameters:
        newRequest - the xml.
      • setRequestEncoding

        void setRequestEncoding​(String newEncoding)
        Set the encoding to use when converting the request from characters to bytes. The default is the Java UTF8 encoding. Set to null to use the system default encoding.
        Parameters:
        newEncoding - the encoding.
      • setHTTPEncoding

        @Deprecated
        void setHTTPEncoding​(String newEncoding)
        Deprecated.
        Set the encoding to use when converting the response HTTP headers from bytes to characters. The default is the Java UTF8 encoding. Set to null to use the system default encoding.
        Parameters:
        newEncoding - the encoding.
      • setResponseEncoding

        void setResponseEncoding​(String newEncoding)
        Set the encoding to use when converting the response from bytes to characters. The default is the Java UTF8 encoding. Set to null to use the system default encoding.
        Parameters:
        newEncoding - the encoding.
      • setURL

        void setURL​(String newURL)
        Set the URL to which to send the SOAP request.
        Parameters:
        newURL - the url.
      • setSOAPAction

        void setSOAPAction​(String newAction)
        Set the SOAP action to which to send the SOAP request. Use setSOAPAction(null) to clear the soap action.
        Parameters:
        newAction - the SOAP action.
      • setHTTPHeader

        void setHTTPHeader​(String header,
                           String value)
        Set an HTTP header. The Content-Length header can not be set. The following headers are required and have defaults:
        • Host - set to the host of the URL
        • Content-Type - set to text/xml
        • User-Agent - set to USER_AGENT
        Use setHTTPHeader(header, null) to clear a header. The following headers configure the system and are not sent over the wire:
        • X-Internal-SOTimeout - value for socket timeout, in milliseconds. If not specified there is no timeout.
        • X-Internal-ByteWrite - write output one byte at a time instead of as a buffer. Default is to use a buffer.
        Parameters:
        header - the header to set.
        value - the value.
      • setAuthentication

        void setAuthentication​(String username,
                               String password)
        Set the username and password for basic authentication. There is one special parameter value that can be passed as the username to control credential usages. This is REDWOOD_NOCREDENTIAL. The behavior of this value is documented with the constant.
        Parameters:
        username - the username, or one of the options to control credential use.
        password - the password.
      • setLogger

        void setLogger​(Logger logger)
        Set the logger class used to log SOAP in/output from the HTTP client.
        Parameters:
        logger - Log class
      • handleHTTPResponse

        void handleHTTPResponse()
                         throws HTTPException
        Handle the HTTP response, particularly the HTTP response line. It will throw an HTTPException if the response code is not 200, with the following exception for response code 500: If the HTTP response code is 500 and parseHTTP500Response is true, then this method will not throw an exception for an HTTP 500 response. If parseHTTP500Response is false then an HTTP exception will be thrown in this situation.
        Throws:
        HTTPException - if the response cannot be handled
      • handleSOAPResponse

        void handleSOAPResponse()
                         throws SAXException
        Handle the SOAP response, this will extract the namespaces from the response, and check if it is a SOAP fault. There is no need to call populateNamespacesFromResponse() if this method has been called.
        Throws:
        SAXException - it the response is not valid XML.
        SOAPFaultException - if the response is a SOAP fault.
      • sendRequest

        void sendRequest​(boolean getResponse)
                  throws IOException
        Send the request, but do not yet handle the response. If getResponse is true, the response will be read but not processed. If getResponse is false, the response wil not be read at all. The socket is opened and closed in this method. If getResponse is set to false, there is no way of reading the response.
        Parameters:
        getResponse - true to read the response, false to ignore it.
        Throws:
        IOException - if an IO error occurs.
      • getResponseInputStream

        InputStream getResponseInputStream()
        Get the response inputStream. If the inputStream is already consumed a IllegalAccessError is thrown.
        Returns:
        the response inputStream.
      • getResponseXML

        String getResponseXML()
        Get the response XML as a string. If the response is already consumed a IllegalAccessError is thrown.
        Returns:
        the response XML.
      • parseResponseXML

        void parseResponseXML​(DefaultHandler handler)
                       throws SAXException
        Parse the response XML.
        Parameters:
        handler - the content handler.
        Throws:
        SAXException - if a SAX exception occurs.
      • transformResponseXML

        void transformResponseXML​(Transformer transformer,
                                  Result result)
        Transform the XML response using the transformer to the result.
        Parameters:
        transformer - the transformer to use.
        result - the result to use.
      • transformResponseXMLWithXSLT

        void transformResponseXMLWithXSLT​(Source source,
                                          Result result)
        Transform the XML response using the specified XSLT.
        Parameters:
        source - the source for the XSLT.
        result - the result to use.
      • transformResponseXMLWithXSLTDirect

        void transformResponseXMLWithXSLTDirect​(String xslt,
                                                Result result)
        Transform the XML response using the XSLT in the specified string.
        Parameters:
        xslt - the XSLT.
        result - the result to use.
      • transformResponseXMLWithXSLTFile

        void transformResponseXMLWithXSLTFile​(File xslt,
                                              Result result)
        Transform the XML response using the XSLT in the specified file.
        Parameters:
        xslt - the XSLT file.
        result - the result to use.
      • populateNamespacesFromResponse

        void populateNamespacesFromResponse()
                                     throws SAXException
        Populate namespaces from the response.
        Throws:
        SAXException - if namespaces cannot be determined.
      • clearNamespaces

        void clearNamespaces()
        Clear the XML namespace mapping.
      • getNamespaces

        Map<String,​String> getNamespaces()
        Get a read only copy of the namespace mapping.
        Returns:
        the namespace mapping.
      • getNSPrefixForURIWithColon

        String getNSPrefixForURIWithColon​(String uri)
        Get a namespace prefix for given namespace URI (if there are multiple mappings to the same URI there is no guarantee which is returned). If uri is null, empty or non-existent, "" (empty string) is returned. If the namespace is found it is returned with : appended (e.g. redwood.com:)
        Parameters:
        uri - the uri to get the namespace prefix for.
        Returns:
        the namespace prefix appended with : when found, or "" (empty string) if not found
      • setNamespace

        void setNamespace​(String prefix,
                          String uri)
        Map an XML namespace prefix to a URI.
        Parameters:
        prefix - the prefix.
        uri - the URI.
      • setNamespaceDone

        void setNamespaceDone()
        Set a flag indicating that all namespaces have been added.
      • setDefaultNSPrefix

        void setDefaultNSPrefix​(String newValue)
        Set the prefix for the default namespace in XPath. The default is 'default';
        Parameters:
        newValue - the new value.
      • getStringByXPath

        String getStringByXPath​(String xPath)
        Use an XPath to get a String from the response. To access the default namespace (defined by <.. xmlns="uri">) use the value specified to setDefaultNSPrefix(String). The default value is default, so to access an element in the default namespace, use default:element. For example, if the response is:
             <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
               <soap:Body>
                 <ConversionRateResponse xmlns="http://www.webserviceX.NET/">
                   <ConversionRateResult>0.5746</ConversionRateResult>
                 </ConversionRateResponse>
               </soap:Body>
             </soap:Envelope>
             
        The result can be printed using the following XPath (assuming the defaultNSPrefix is set to default):
               System.out.println("'" + req.getResponseXPathString("/soap:Envelope/soap:Body/default:ConversionRateResponse/default:ConversionRateResult") + "'");
             
        If defaultNSPrefix is set to 'anon':
               System.out.println("'" + req.getResponseXPathString("/soap:Envelope/soap:Body/anon:ConversionRateResponse/anon:ConversionRateResult") + "'");
             
        Parameters:
        xPath - an XPath.
        Returns:
        the result.
      • getElementValuesByXPath

        List<String> getElementValuesByXPath​(String xPath)
        Use an XPath to get a String Array from the response, see getStringByXPath(String).
        Parameters:
        xPath - an XPath.
        Returns:
        the result.
      • getBigDecimalByXPath

        BigDecimal getBigDecimalByXPath​(String xPath)
        Use an XPath to get a BigDecimal from the response, see getStringByXPath(String).
        Parameters:
        xPath - an XPath.
        Returns:
        the result.
      • getDateTimeZoneByXPath

        DateTimeZone getDateTimeZoneByXPath​(String xPath)
                                     throws ParseException
        Use an XPath to get a DateTimeZone from an xsd:date, xsd:time or xsd:dateTime from the response.
        Parameters:
        xPath - an XPath.
        Returns:
        the result.
        Throws:
        ParseException
      • getHTTPResponseCode

        int getHTTPResponseCode()
        Get the HTTP response code.
        Returns:
        the numeric response code.
      • getHTTPResponseLine

        String getHTTPResponseLine()
        Get the first HTTP response line.
        Returns:
        the response line.
      • getHTTPResponseHeaders

        Map<String,​List<String>> getHTTPResponseHeaders()
        Get the HTTP response headers as a Map, keys are Strings in lowercase, values are List objects of String.
        Returns:
        a map containing the headers, or an empty Map if there is no HTTP response yet.
      • setParseHTTP500Response

        void setParseHTTP500Response​(boolean newValue)
        Should an HTTP 500 response be parsed as a SOAPfault? Default: true.
        Parameters:
        newValue - the new value.
      • setMethod

        void setMethod​(String method)
        Set the HTTP method to use, default is POST. Only ever change this if the service being called supports the chosen method.
        Parameters:
        method - the method to use.
      • setSocketFactory

        @Deprecated
        void setSocketFactory​(SocketFactory factory)
        Deprecated.
        this is no longer functional.
        Set the socket factory to use for sockets created by this SOAP request. This is ignored. Use a _HTTPS_ URL to get an encrypted connection.
        Parameters:
        factory - the factory to use.
      • setRejectedCipherSuitePatterns

        @Deprecated
        void setRejectedCipherSuitePatterns​(String patterns)
        Deprecated.
        Set the list of cipher suite patterns to reject. This is ignored. Use the Configuration settings to set cipher suites.
        Parameters:
        patterns - a comma separated list of strings, any cipher suite that contains any of these strings will be rejected.
      • setProxy

        @Deprecated
        void setProxy​(String host,
                      int port,
                      String username,
                      String password)
        Deprecated.
        Use the new global proxy support
        Set the proxy to use. This is obsolete and is no longer implemented.
        Parameters:
        host - the proxy hostname
        port - the proxy port
        username - the username
        password - the password