Sending a Fax

SendCharFaxTest

The InterFax sendCharFax() web service method lets you fax a text document. We'll build a simple class that calls that method to demonstrate sending a simple Java String instance as a fax message using the sendCharFax() web service. The actual service call is again highlighted in red.

import cc.interfax.www.SendCharFax;
import cc.interfax.www.SendCharFaxResponse;
 
public class SendCharFaxTest {
 
    public void run() throws Exception {
        cc.interfax.www.InterFaxSoapStub theBinding;
        try {
           theBinding = (cc.interfax.www.InterFaxSoapStub)
                        new cc.interfax.www.InterFaxLocator().getInterFaxSoap();
        }
        catch (javax.xml.rpc.ServiceException jre) {
            if(jre.getLinkedCause()!=null)
                jre.getLinkedCause().printStackTrace();
            throw new RuntimeException("JAX-RPC ServiceException caught: " + jre);
        }
 
        // Time out after a minute
        theBinding.setTimeout(60000);
 
        // Send a simple text fax using the InterFax sendCharFax() web service method.
        System.out.println("Sending Fax using sendCharFax()");
        SendCharFax theParams = new SendCharFax(TestConstants.USERNAME,
              TestConstants.PASSWORD,
              TestConstants.FAX_NUMBER,
              "This is a test fax message.",
              "TXT");
 
        SendCharFaxResponse theResponse = theBinding.sendCharFax(theParams);
 
        long theReturnCode = theResponse.getSendCharFaxResult();
        System.out.println("sendCharFax() call returned with code: " + theReturnCode);
    }
 
    public static void main(String[] anArgs) {
        try {
            new SendCharFaxTest().run();
        } catch(Exception theE) {
           System.out.println("Error encountered while running SendCharFaxTest:");
           theE.printStackTrace();
        }
     }
}

We'll again add a target to our ANT build script so we can run this test program using ANT.

<target name="run-send-char-fax-test" depends="dist" description="Test that makes a SendCharFaxTest call" >
    <java classname="SendCharFaxTest">
       <arg value="-h"/>
       <classpath>
         <pathelement location="dist/Interfax.jar"/>
         <pathelement path="${build}/test/"/>
         <pathelement path="${java.class.path}"/>
         <path refid="compile.classpath"/>
       </classpath>
    </java>
</target>

When you run this test, you should see output similar to the output below indicating a successful fax transmission.

$ ant run-send-char-fax-test
Buildfile: C:\workspace\InterfaxJavaTutorial\build.xml
init:
code.generation:
[axis-wsdl2java] - Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled.
[axis-wsdl2java] WSDL2Java https://ws.interfax.net/DFS.asmx?WSDL
[axis-wsdl2java] Parsing XML file:  https://ws.interfax.net/DFS.asmx?WSDL
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\CancelFileUpload.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\ReSendFaxResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendfaxEx_2Response.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\GetSupportedFileTypes.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\Sendfax.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendfaxEx_2.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\IsSupportedFileTypeResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxStatusXML.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxQueryResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\HideFaxResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendCharFaxResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxItem.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxStatus.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\CancelFileUploadResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendfaxEx.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxStatusExResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxStatusResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\HideFax.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxItemEx.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\GetFaxImage.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxQuery.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\IsSupportedFileType.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxStatusXMLResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\GetFaxImageResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendCharFax.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\UploadFileChunk.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\FaxStatusEx.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendfaxResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\SendfaxExResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\GetSupportedFileTypesResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\StartFileUpload.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\StartFileUploadResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\UploadFileChunkResponse.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\ReSendFax.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\InterFaxSoap.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\InterFaxSoapStub.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\InterFax.java
[axis-wsdl2java] Generating C:\workspace\InterfaxJavaTutorial\generated\cc\interfax\www\InterFaxLocator.java
compile:
    [javac] Compiling 38 source files to C:\workspace\InterfaxJavaTutorial\build\dist
    [javac] Note: Some input files use unchecked or unsafe operations.
    [javac] Note: Recompile with -Xlint:unchecked for details.
    [javac] Compiling 2 source files to C:\workspace\InterfaxJavaTutorial\build\test
dist:
      [jar] Building jar: C:\workspace\InterfaxJavaTutorial\dist\Interfax.jar
run-send-char-fax-test:
     [java] - Unable to find required classes (javax.activation.DataHandler and javax.mail.internet.MimeMultipart). Attachment support is disabled.
     [java] Sending Fax using sendCharFax()
     [java] sendCharFax() call returned with code: 45196105
BUILD SUCCESSFUL
Total time: 18 seconds

Full documentation for SendCharFax can be found online here: SendCharFax API documentation.

If you need to send a PDF document, or a Microsoft Word document, you would not use the sendCharFax() method. Instead, you would use an alternate method, like sendFax(). We'll demonstrate how to do this below.

SendFaxTest

Faxing a PDF document with the sendFax web service method is much the same as faxing a character data using sendCharFax, except that we're sending a binary file which we manipulate as an array of bytes. We'll create and use a utility method to get the byte[] representation of the file we're going to fax, then simply hand this representation to our Axis-generated SOAP stub which will send it out as a fax message.

import cc.interfax.www.Sendfax;
import cc.interfax.www.SendfaxResponse;
 
public class SendFaxTest {
 
    public void run() throws Exception {
        cc.interfax.www.InterFaxSoapStub theBinding;
        try {
           theBinding = (cc.interfax.www.InterFaxSoapStub)
                        new cc.interfax.www.InterFaxLocator().getInterFaxSoap();
        }
        catch (javax.xml.rpc.ServiceException jre) {
            if(jre.getLinkedCause()!=null)
                jre.getLinkedCause().printStackTrace();
            throw new RuntimeException("JAX-RPC ServiceException caught: " + jre);
        }
 
        // Time out after a minute
        theBinding.setTimeout(60000);
 
        // Encode the File.
        byte[] theFileData = TestUtils.transformToBytes(TestConstants.PDF_FILENAME);
 
        System.out.println("Sending Fax using sendFax().  Document size: " + theFileData.length);
 
        Sendfax theParams = new Sendfax(TestConstants.USERNAME,
                TestConstants.PASSWORD,
                TestConstants.FAX_NUMBER,
                theFileData,
                "PDF");
        SendfaxResponse theResponse = theBinding.sendfax(theParams);
        System.out.println("sendFax() call returned with code: " + theResponse.getSendfaxResult());
    }
 
    public static void main(String[] anArgs) {
        try {
            new SendFaxTest().run();
        } catch(Exception theE) {
           System.out.println("Error encountered while running SendFaxTest:");
           theE.printStackTrace();
        }
     }
}

Here's the utility method TestUtils.transformToBytes that does basic Java IO to get a byte[] representation of a specified file.

public static byte[] transformToBytes(String aFilename)
    throws Exception {
 
    if(null==aFilename) {
        throw new NullPointerException("aFilename is null");
    }
    File theFile = new File(aFilename);
    if(!theFile.isFile()) {
        throw new IllegalArgumentException("Path doesn't represent a file: " + aFilename);
    }
    if(!theFile.exists()) {
        throw new IllegalArgumentException("File not found: " + aFilename);
    }
 
    InputStream theIs = new BufferedInputStream(new FileInputStream(theFile));
    ByteArrayOutputStream theRawData = new ByteArrayOutputStream();
 
    byte theBuffer[] = new byte[1024];
    int theBytesRead;
 
    try {
        while((theBytesRead=theIs.read(theBuffer)) != -1) {
 
            //System.out.println("read: " + theBytesRead + " bytes.");
 
            if( theBytesRead < 1024 ) {
                byte theSlice[] = new byte[theBytesRead];
                System.arraycopy(theBuffer, 0, theSlice, 0, theBytesRead);
                theRawData.write(theSlice);
            } else {
                theRawData.write(theBuffer);
            }
        }
    } finally {
        theIs.close();
        theRawData.close();
    }
 
    return theRawData.toByteArray();
}

You can run this test of the SendFax method like we've run the previous test--by adding an ANT task to run it or by running it like any Java class with a main() method.

Full documentation for SendFax can be found online here: SendFax API documentation.

These examples should be enough to get you started with the InterFax Web Services API. The API itself does much more than what has been shown in this tutorial and you can study the online documentation learn more: http://www.interfax.net/en/dev/webservice/index.html. You will see that you can send multiple faxes at once, schedule fax transmission for a later time, decorate your faxes with page headers, query for the status of your fax submissions, and lots more. All of these features are very easy to access because you have already generated a stub class to call all of the InterFax web service methods using the same approach we've used in the examples above. The code bundle that goes along with this tutorial has examples of how to use many of the API methods not described in this tutorial, it's a great place to look for more detail.

If you find that you need additional help with your Java programs that use the InterFax web service, you can post to the developer forums online: http://forum.interfax.net/viewforum.php?id=2.

‹ Learn By Doing: Building a Web Service ClientupWeb Services Primer ›