Overview (fax4j 0.45.0 API)

Packages
Package	Description
org.fax4j	The fax4j library, is a standard on which java based applications can communicate with fax devices in order to submit new faxes or perform other related actions.
org.fax4j.bridge	Provides the API classes for the fax client bridge. The fax4j bridge is used to transform applications to fax bridges for example an email server to provide email2fax functionality.
org.fax4j.bridge.email	Provides the API classes for the email2fax bridge.
org.fax4j.bridge.http	Provides the API classes for a HTTP based web2fax bridge.
org.fax4j.bridge.process	Provides the API classes for a standalone process based cli2fax bridge.
org.fax4j.common	Contains common internal classes used by the fax4j library.
org.fax4j.spi	Provides the API classes for the fax client SPI. The class/interfaces defined in this package should only be used internally by the fax4j library or by classes implemeting a new fax client SPI.
org.fax4j.spi.adapter	Provides the adapter fax client SPI implementation.
org.fax4j.spi.comm	Provides the COMM port communication based fax client SPI implementation.
org.fax4j.spi.efax	Provides the efax based fax client SPI implementation.
org.fax4j.spi.email	Provides the email based fax client SPI implementation.
org.fax4j.spi.extremefax	Provides the extreme fax based fax client SPI implementation.
org.fax4j.spi.faxage	Provides the faxage based fax client SPI implementation.
org.fax4j.spi.hoiio	Provides the hoiio based fax client SPI implementation.
org.fax4j.spi.http	Provides the HTTP based fax client SPI implementation.
org.fax4j.spi.hylafax	Provides the HylaFAX fax client SPI implementation.
org.fax4j.spi.interfax	Provides the interfax based fax client SPI implementation.
org.fax4j.spi.java4less	Provides the java4less RFax fax client SPI implementation.
org.fax4j.spi.linux	Provides the native linux fax client SPI implementation.
org.fax4j.spi.mac	Provides the native Mac fax client SPI implementation.
org.fax4j.spi.metrofax	Provides the metrofax based fax client SPI implementation.
org.fax4j.spi.nextivafax	Provides the nextivafax based fax client SPI implementation.
org.fax4j.spi.phaxio	Provides the phaxio based fax client SPI implementation.
org.fax4j.spi.process	Provides the process based fax client SPI implementation. These implementations use external executables/scripts to invoke fax actions.
org.fax4j.spi.send2fax	Provides the send2fax based fax client SPI implementation.
org.fax4j.spi.vbs	Provides the VB script based fax client SPI implementation.
org.fax4j.spi.windows	Provides the native windows fax client SPI implementation.
org.fax4j.util	Provides general utilities used internally by the fax4j library.

Overview:

The fax4j library is a standard on which java based applications can communicate with fax devices in order to submit new faxes or perform other related actions.
The fax4j starting point is the org.fax4j.FaxClientFactory which enables to return a new instance of the org.fax4j.FaxClient used to perform the fax actions.

Installing fax4j:

As any java library, the fax4j.jar must be located in the application classpath in order to be used.
Some SPIs (will be explained in more detail later on), require additional third party jars or native libraries.
All are found in the lib directory as part of the fax4j distribution package.

In addition to any jar/native lib needed, the fax4j also accepts external configuration file (fax4j.properties, will be explained in more details later on) which also, if defined, is required to be located in the application classpath in order to be used.

For maven projects, all that is needed to include the fax4j in your project is to declare it as a dependency as defined in the following report: dependency-info

Coding with fax4j:

This following section will provide general details on how to code with the fax4j API.

The first part before doing any fax related action is getting a fax client instance.
Typical applications would only create 1 single instance of the fax client and reuse it throughout the lifetime of the process.
Fax clients are thread safe and can be used in multi threaded applications.
To get an instance of the fax client, use the fax client factory as follows:

    //get new instance of a fax client (based on internal + external fax4j.properties file data)
    FaxClient faxClient=FaxClientFactory.createFaxClient();

It is possible to also provide additional fax4j configuration and request a specific implementation during the fax client creation via fax client factory method: createFaxClient(String type,Properties configuration).
For example:

    //get new instance of a fax client with windows SPI and using also configuration defined in myProperties
    FaxClient faxClient=FaxClientFactory.createFaxClient("windows",myProperties);

With the fax client instance all fax actions are possible.
The fax client is thread safe therefore you can create only one instance of it and reuse it throughout your application lifetime and in a multi threaded scenarios.

The next step is to create a fax job instance.
The fax job object holds all data related to any future or existing fax job.
It is used by the fax client to invoke any fax related action such as submitting a new fax, canceling existing fax and so on.
To create a fax job use the following code:

    //create a new fax job
    FaxJob faxJob=faxClient.createFaxJob();

Sending a Fax:

After acquiring a fax client and creating a fax job, you will need to populate all relevant fax info in the fax job.
For example:

    //set fax job values
    faxJob.setFile(new File("./my_document.txt"));
    faxJob.setPriority(FaxJobPriority.HIGH_PRIORITY);
    faxJob.setTargetAddress("555-555");
    faxJob.setTargetName("YourName");
    faxJob.setSenderEmail("myemail@mycompany.com");
    faxJob.setSenderName("MyName");

Once the fax job contains all the needed info, you submit it via fax client:

    //submit fax job
    faxClient.submitFaxJob(faxJob);

The submitFaxJob may than update the fax job object (for example may populate the fax job ID) so it is important to keep this instance and reuse it for any fax activity relevant for this job (for example if you later on would like to cancel the fax submission).

Additional Fax Activities:

After submitting a fax job, you can use the fax job instance to invoke additional activities such as: suspending, resuming and canceling the fax job.
These activities will only have effect if the fax job was not sent yet by the fax server and is still in submitted status.
Here is sample code to suspend a fax job:

    //suspend fax job
    faxClient.suspendFaxJob(faxJob);

The faxClient.getFaxJobStatus method enables you to get the current status of the fax job and holds the following values:

PENDING - The 'Pending' status is returned in case fax job has not been submitted yet by the fax server but it is still in the queue.
Suspended fax jobs are also considered as pending.
IN_PROGRESS - The 'In Progress' status is returned in case the fax server is currently handling the fax job.
ERROR - The 'Error' status is returned in case there was an error during the fax server attempt to submit the fax job.
UNKNOWN - In case the status is unknown

Fax Events:

It possible to add listeners on the fax client to monitor for any fax event.
There are 2 types of events: client actions events and monitoring events.
Simply implement the FaxClientActionEventListener or FaxMonitorEventListener interface and invoke the relevant FaxClient add listener method with an instance of the listener.
The client action listener picks up events based on actions invoked on the fax client and not based on the status changes of the actual fax job.
For example if a fax job is submitted via fax client, than the faxJobSubmitted event method will be invoked.
However the fax job itself might still be pending transmission by the actual fax modem/server.
On the other hand, the fax monitor events enable to listen on status change events coming from the remote fax modem (not supported by all SPIs).
The basic implementation of the fax monitoring events is based on polling for status changes by the SPI which could increase the load on the system, therefore it is re commanded to listen to such event only when needed.
Also fax jobs will be monitored only if there are active listeners registered.
If the listeners are added after a fob job was submitted, that fax job would not be monitored.

Fax Interceptors:

It is possible to define interceptors that will get invoked for all fax activities.
Unlike the fax events the interceptors are created by the fax4j library via configuration and not manually and in addition it enables you to modify the input/output.
One possible use for the interceptors is logging, for example the built in fax4j logging interceptor org.fax4j.spi.LogFaxClientSpiInterceptor enables to log the input/output of every method.
Another possible use is to push common data to the fax job before submitting the fax.
For example if you have a common return email or if you want to update the fax content with some common company logo you can create an interceptor that will update the fax job object before the submit fax job method is invoked.

To implement an interceptor you must implement the org.fax4j.spi.FaxClientSpiInterceptor interface (or extend org.fax4j.spi.AbstractFaxClientSpiInterceptor).
In addition you will have to update the fax4j configuration as follows:

org.fax4j.proxy.enabled=true (this is already defaulted to this value in the internal fax4j properties)
org.fax4j.proxy.interceptor.list=aaa;bbb (The interceptor list (separated by ';'), for example the default value is: org.fax4j.proxy.interceptor.list=log)
for every interceptor in the interceptor list you must define the following:
org.fax4j.proxy.interceptor.type.aaa=MyAAAInterceptor
org.fax4j.proxy.interceptor.type.bbb=MyBBBInterceptor
For example the default log interceptor is defined as follows:
#The interceptor class name for type log
org.fax4j.proxy.interceptor.type.log=org.fax4j.spi.LogFaxClientSpiInterceptor

Fax Bridges:

The fax bridge is a wrapper to the fax client used to create X2Fax bridges.
It enables for example to create email2fax or web2fax applications easily.
While the fax client has a generic, standard API to invoke fax actions, the fax bridge has different API per context.
For example, an email2fax bridge would have an email as an input with very limited amount of data.
Another example is the web2fax bridge would have a HTTP request as input.
To implement a bridge you must implement the FaxBridge interface (or extend AbstractFaxBridge).
In the caller code you must first create an instance of the bridge and initialize it.
Typical applications would only create one single instance of the fax bridge and reuse it throughout the lifetime of the process.
The x2fax subproject already comes with built-in email component to enhance email servers to provide email2fax services and HTTP servers and WARs to convert any web server to a web2fax bridge.

Vendor Policy:

The vendor policy enables vendors to hook into the fax submitting flow, enabling to restrict access, bill customers and so on, before/after the fax is submitted.
Vendor policy is only relevant for flows going via fax bridge and not through the fax client, therefore applications not using fax bridges can ignore this class.

Configuring fax4j:

The configuration of the fax4j framework is made up of 3 layers.
The configuration is based on simple properties.
Each layer overrides the lower layers by adding/changing the property values.

The first layer is the internal fax4j.properties file located in the fax4j jar.
This layer contains the pre-configured values for the fax4j framework and can be changed by updating these properties in the higher layers.
This layer is part of the fax4j and should not be tempered with directly.
The second layer is the external fax4j.properties file that is located on the classpath.
This file is optional and provides the ability to override the internal configuration for the entire fax4j framework.
The top most layer is the optional java.util.Properties object provided by the external classes when creating a new fax client (via FaxClientFactory.createFaxClient method).
These properties enable to override the configuration of the lower 2 layers.

Below table describes the basic configuration values, for SPI specific configuration, see the relevant SPI class javadoc (and later sections).

Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.type.map.xxx	For each SPI type, there is a property that (with prefix: org.fax4j.spi.type.map. and type name for example: org.fax4j.spi.type.map.adapter) which defines the SPI class name for the given SPI type. For example: org.fax4j.spi.type.map.adapter=org.fax4j.spi.adapter.AdapterFaxClientSpi Means that for SPI type adapter, the SPI class to be used is org.fax4j.spi.adapter.AdapterFaxClientSpi	org.fax4j.spi.type.map.adapter=org.fax4j.spi.adapter.AdapterFaxClientSpi org.fax4j.spi.type.map.windows=org.fax4j.spi.windows.WindowsFaxClientSpi org.fax4j.spi.type.map.vbs=org.fax4j.spi.vbs.VBSFaxClientSpi org.fax4j.spi.type.map.mail=org.fax4j.spi.email.MailFaxClientSpi org.fax4j.spi.type.map.http=org.fax4j.spi.http.HTTPFaxClientSpi org.fax4j.spi.type.map.process=org.fax4j.spi.process.ProcessFaxClientSpi org.fax4j.spi.type.map.linux=org.fax4j.spi.linux.LinuxFaxClientSpi org.fax4j.spi.type.map.mac=org.fax4j.spi.mac.MacFaxClientSpi org.fax4j.spi.type.map.hylafax=org.fax4j.spi.hylafax.HylaFaxClientSpi org.fax4j.spi.type.map.comm=org.fax4j.spi.comm.CommFaxClientSpi org.fax4j.spi.type.map.interfax=org.fax4j.spi.interfax.InterfaxMailFaxClientSpi org.fax4j.spi.type.map.nextivafax=org.fax4j.spi.nextivafax.NextivafaxMailFaxClientSpi org.fax4j.spi.type.map.send2fax=org.fax4j.spi.send2fax.Send2FaxMailFaxClientSpi org.fax4j.spi.type.map.metrofax=org.fax4j.spi.metrofax.MetroFaxMailFaxClientSpi org.fax4j.spi.type.map.faxage=org.fax4j.spi.faxage.FaxAgeMailFaxClientSpi org.fax4j.spi.type.map.extremefax=org.fax4j.spi.extremefax.ExtremeFaxMailFaxClientSpi org.fax4j.spi.type.map.efax=org.fax4j.spi.efax.EFaxMailFaxClientSpi org.fax4j.spi.type.map.phaxio=org.fax4j.spi.phaxio.PhaxioFaxClientSpi org.fax4j.spi.type.map.hoiio=org.fax4j.spi.hoiio.HoiioFaxClientSpi org.fax4j.spi.type.map.rfax=org.fax4j.spi.java4less.RFaxFaxClientSpi	NA	NA
org.fax4j.spi.default.type	In case the SPI type was not provided in the createFaxClientSpi method, the type will be taken from this property value.	adapter	none	false
org.fax4j.logger.class.name	Defines the internal fax4j logger class name. The logger must implement the org.fax4j.common.Logger interface and have an empty constructor. This property can only be set in the internal fax4j.properties and the fax4j.properties on the classpath, providing these values as part of the java.util.Properties input of the createFaxClientSpi will have no affect.	org.fax4j.common.SimpleLogger	org.fax4j.common.SimpleLogger	false
org.fax4j.logger.log.level	Defines the internal fax4j logger log level. The possible values are: DEBUG, INFO and ERROR. This property can only be set in the internal fax4j.properties and the fax4j.properties on the classpath, providing these values as part of the java.util.Properties input of the createFaxClientSpi will have no effect.	ERROR	ERROR	false
org.fax4j.client.class.name	Defines the fax client class name. Since the fax client redirects the operations to the SPI (the engine) classes, creating a custom fax client is not required.	org.fax4j.FaxClient	org.fax4j.FaxClient	false

The Logger:

The default fax4j logger is the org.fax4j.common.SimpleLogger which simply writes to the standard output/errput streams, based if it is a debug/info or error log message.
It is possible to use a custom logger which can proxy to the application logger by implementing org.fax4j.common.Logger (or extending the default org.fax4j.common.SimpleLogger) and then pointing to the custom logger in the external log4j.properties file via org.fax4j.logger.class.name property.
The log level is also configured in the fax4j.properties and can be modified in the external log4j.properties by setting the org.fax4j.logger.log.level property value to DEBUG, INFO or ERROR.

Error Handling:

For any error that requires more information than what the default logs/exceptions provide, you can turn on full debug logging by following the below steps:
1. Create a fax4j.properties file (if you don't have one already) and put it in your classpath
2. Write the following line in the file: org.fax4j.logger.log.level=DEBUG
With this configuration full logging is enabled.
"No internal SPI available." error thrown - This error means that the fax4j was unable to find a suitable SPI for your platform/configuration.
To solve you will have to either configure the relevant SPI correctly or select a specific SPI when creating the fax client.
For example:
//get new instance of a fax client with Windows SPI
FaxClient faxClient=FaxClientFactory.createFaxClient("windows",null);
"Error while invoking fax action process, exit code: 128" error thrown when running with Windows SPI on windows - This error may be due to missing windows dll from the windows installation.
In order to find out which dll is missing you can run the fax4j.exe (found inside the fax4j.jar, so first extract it and the fax4j.dll to some temporary folder) with your values as follows:
fax4j.exe -action "submit" -target_address "555-555" -target_name "YourName" -sender_name "MyName" -file "./my_document.txt"
In case of a missing dll, windows will show an error dialog with the name of the missing dll (for example: "missing msvcr100.dll")
"The data is invalid." error thrown when running with VBS SPI on windows - This VBS error can have multiple root causes:
1. The file to be faxed is empty.
2. The file to be faxed must have the "print" option enabled when right clicking on the file in windows.
  If it does not, you must associate the file extension with a program that support the print action.
  For example, you can associate .txt files with notepad to enable the print option.
3. The java process does not have the required permissions to invoke fax actions.
  This may happen if you run the java process as a windows service but did not provide the user credentials to the windows service definition.

The SPIs:

The engine behind the fax client is the fax client SPI which is used internally.
Each SPI provides a different means to invoke the fax actions and may be suited for different platforms and needs.
For example the VBSFaxClientSpi and WindowsFaxClientSpi use the windows APIs to invoke fax actions and do not require any third parties however they are only available on windows platforms.
The MailFaxClientSpi is available on all platforms but it is using email servers that are able to convert emails to faxes so it is depended on that support in the email server.
The SPIs are not used directly by the application code, instead they are used internally by the fax4j library.
However the application code using fax4j is required to configure the fax4j.properties or request via code a specific SPI that suites its needs.
The following section will go over all SPIs in general.

org.fax4j.spi.adapter.AdapterFaxClientSpi

This implementation will proxy the requests to another internal SPI.
The internal SPI created will be based on configuration in the fax4j properties.
The configuration contains conditions such as OS, availability of java classes, availability of native libraries, availability of executables or validation that a certain fax4j property is defined and contains a value.
Once all conditions are met the internal SPI is created, otherwise the next SPI configuration is used.
If no SPI conditions are met, an exception will be thrown.
This SPI is the default SPI in fax4j as it has the "ability" (based on configuration) to find the most appropriate SPI based on the platform and configuration the application is running on.
For example with default fax4j configuration and if running on windows, the adapter SPI will automatically select the WindowsFaxClientSpi SPI.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.adapter.internal.spi.types	A ';' separated list of SPI types. This SPI will go over the list one by one based on the configured order and will validate the type conditions. Once an SPI is found for which all conditions are met, the adapter SPI will create an instance of it and use it to proxy all fax operations to.	mail;http;process;phaxio;hoiio;windows;vbs;linux;mac;hylafax;comm;interfax;nextivafax;send2fax;metrofax;faxage;extremefax;efax;rfax	none	true
org.fax4j.spi.adapter.internal.spi.condition.xxx	For each type defined in the org.fax4j.spi.adapter.internal.spi.types property, you can define custom conditions to validate. These conditions include: property - checks a fax4j property is defined and contains a value OS - checks OS name contains the value (case insensitive) java-class - checks that java class can be loaded native-lib - checks that native lib can be loaded executable - checks executable is on system path stable - checks for a fax4j property org.fax4j.spi.xxx.stable is defined and equals true, where xxx is the SPI key (for example: org.fax4j.spi.adapter.stable=true) Conditions are separated by a ';' character and the condition type and value are separated by the ':' character, for example: org.fax4j.spi.adapter.internal.spi.condition.vbs=OS:windows;executable:cscript.exe The following conditions are always checked (even if not defined): property:org.fax4j.spi.type.map.xxx where xxx is the SPI key (for example: org.fax4j.spi.type.map.adapter) java-class:xxx where xxx is the SPI class name based on the fax4j mapping (for example: org.fax4j.spi.type.map.adapter=org.fax4j.spi.adapter.AdapterFaxClientSpi) stable	org.fax4j.spi.adapter.internal.spi.condition.windows=OS:windows;native-lib:winfax org.fax4j.spi.adapter.internal.spi.condition.vbs=OS:windows;executable:cscript.exe org.fax4j.spi.adapter.internal.spi.condition.mail=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.address.template;property:org.fax4j.spi.mail.subject.template;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.http=property:org.fax4j.spi.http.client.class.name;property:org.fax4j.spi.http.host.name;property:org.fax4j.spi.http.faxjob2request.converter.class.name;property:org.fax4j.spi.http.response.handler.class.name org.fax4j.spi.adapter.internal.spi.condition.process=property:org.fax4j.spi.process.submit.template.command org.fax4j.spi.adapter.internal.spi.condition.linux=OS:linux;executable:efax;property:org.fax4j.spi.linux.submit.template.command org.fax4j.spi.adapter.internal.spi.condition.mac=OS:mac;property:org.fax4j.spi.mac.print.queue.name org.fax4j.spi.adapter.internal.spi.condition.hylafax=property:org.fax4j.spi.hylafax.host;property:org.fax4j.spi.hylafax.user;property:org.fax4j.spi.hylafax.mode;property:org.fax4j.spi.hylafax.type;property:org.fax4j.spi.hylafax.connection.factory.class.name;java-class:gnu.hylafax.HylaFAXClient org.fax4j.spi.adapter.internal.spi.condition.comm=property:org.fax4j.spi.comm.port.name;property:org.fax4j.spi.comm.connection.factory.class.name;property:org.fax4j.spi.comm.fax.modem.class.name org.fax4j.spi.adapter.internal.spi.condition.interfax=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.nextivafax=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.send2fax=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.metrofax=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.faxage=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.extremefax=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.efax=property:org.fax4j.spi.mail.connection.factory.class.name;property:org.fax4j.spi.mail.user.name;property:org.fax4j.spi.mail.password;property:mail.host;java-class:javax.mail.Transport org.fax4j.spi.adapter.internal.spi.condition.phaxio=property:org.fax4j.spi.phaxio.api.key;property:org.fax4j.spi.phaxio.api.secret;java-class:org.json.JSONObject org.fax4j.spi.adapter.internal.spi.condition.hoiio=property:org.fax4j.spi.hoiio.app.id;property:org.fax4j.spi.hoiio.access.token;java-class:org.json.JSONObject org.fax4j.spi.adapter.internal.spi.condition.rfax=property:org.fax4j.spi.rfax.port.name;property:org.fax4j.spi.rfax.fax.class;java-class:com.java4less.rfax.FaxModem	none	true
org.fax4j.spi.adapter.configuration.override.xxx	The adapter SPI enables to override the fax4j configuration for the internal SPI, by defining org.fax4j.spi.adapter.configuration.override.xxx properties where xxx is the original property name for example: org.fax4j.spi.adapter.configuration.override.org.fax4j.proxy.enabled=false overrides the org.fax4j.proxy.enabled property for the internal SPI.	org.fax4j.spi.adapter.configuration.override.org.fax4j.proxy.enabled=false	none	false

org.fax4j.spi.windows.WindowsFaxClientSpi

This implementation will proxy the requests to windows native fax API.
When running on windows and in case no fax4j configuration was changed, this would be the default SPI used.
It is possible to see all faxes submitted from this SPI in the windows fax window available from the Start→Settings→Printers and Faxes→Fax
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.windows.server.name	The fax server host name.	none	none	false
org.fax4j.spi.windows.use.jni	True to use JNI, false to use the external fax4j.exe	false	false	false

Limitations:

This SPI will only work on Windows OS (windows 2000 and up).
See windows fax/tapi limitations.
JNI set to true only supports 32 bit JVMs (Windows OS can be 64 bit).

Dependencies:

Required native libraries: winfax.dll
Windows OS (windows 2000 and up) - see http://msdn.microsoft.com/en-us/library/ms692855(VS.85).aspx for more info.
Windows fax component installed.

org.fax4j.spi.vbs.VBSFaxClientSpi

This implementation will proxy the requests to VB scripts that will invoke the windows fax API.
It is highly re commanded that the windows SPI will be used instead of this SPI.
It is possible to see all faxes submitted from this SPI in the windows fax window available from the Start→Settings→Printers and Faxes→Fax
The executable used to invoke the VBS is defaulted to cscript. It is possible to set a different executable by setting the org.fax4j.spi.vbs.exe.path property.
By default the windows 2000 vbs API will be used on all platforms.
In order for other platforms (other then windows 2000) to invoke the windows XP API, the org.fax4j.spi.vbs.always.use.win2000.api property must be set to false.
However it is recommended not to change this property and keep using the windows 2000 API as the windows XP API does not enable to extract the fax job ID.
In which case it would be than impossible to invoke other fax actions on the specific fax job.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.vbs.server.name	The fax server host name.	none	none	false
org.fax4j.spi.vbs.exe.path	The VBS executable.	cscript.exe	cscript.exe	false
org.fax4j.spi.vbs.always.use.win2000.api	By default the windows 2000 vbs API will be used on all platforms. In order for other platforms (other then windows 2000) to invoke the windows XP API, this property must be set to false.	true	true	false

Limitations:

This SPI will only work on Windows OS (windows 2000 and up).
See windows fax/tapi limitations.

Dependencies:

Required native executable: cscript.exe
Windows OS (windows 2000 and up) - see http://msdn.microsoft.com/en-us/library/ms692855(VS.85).aspx for more info.
Windows fax component installed.

org.fax4j.spi.email.MailFaxClientSpi

This implementation will invoke the requests by sending emails to a mail server that supports conversion between email messages and fax messages.
The mail SPI supports persistent connection to enable to reuse the same connection for all fax operation invocations or to create a new connection for each fax operation invocation.
By default the SPI will create a new connection for each operation invocation however the org.fax4j.spi.mail.persistent.connection set to true will enable to reuse the connection.
To set the user/password values of the mail connection the following 2 properties must be defined: org.fax4j.spi.mail.user.name and org.fax4j.spi.mail.password
All properties defined in the fax4j configuration will be passed to the mail connection therefore it is possible to define mail specific properties (see java mail for more info) in the fax4j properties.
This SPI only supports to submit new fax jobs.
The SPI supports embedding the target destination number into the TO address field and subject field by setting the org.fax4j.spi.mail.address.template and org.fax4j.spi.mail.subject.template properties.
For example: org.fax4j.spi.mail.address.template={0}@myprovider.com
For example: org.fax4j.spi.mail.subject.template=fax:{0}
The {0} will be replaced with the destination number.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.address.template	The address template used when sending the mail message. In order to provide the target fax number as part of the email address you must specify {0} in the template. For example: org.fax4j.spi.mail.address.template={0}@myprovider.com	none	none	true
org.fax4j.spi.mail.subject.template	The subject template used when sending the mail message. In order to provide the target fax number as part of the email subject line you must specify {0} in the template. For example: org.fax4j.spi.mail.subject.template=fax:{0}	none	none	true
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.connection.factory.class.name	The connection factory class name	org.fax4j.spi.email.MailConnectionFactoryImpl	org.fax4j.spi.email.MailConnectionFactoryImpl	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

This SPI is based on the java mail infrastructure, therefore this SPI cannot connect to mail servers through a proxy server.
Currently this SPI only supports submitting new fax jobs.

Dependencies:

Required jar files: mail-1.4.jar, activation-1.1.jar (they are distributed as part of the fax4j, but required to be set in the application classpath)

org.fax4j.spi.process.ProcessFaxClientSpi

This implementation will invoke the requests by executing an external process (executable/script) that enables to invoke the fax action.
This class will use request templates to construct the process command.
The template parameters are updated with the values from the fax4j configuration or FaxJob data.
All template parameters are defined as ${templatename} variables, for example: myexe.exe -target ${target.address} -file ${file}

Below table describes the template parameters.
Template Parameters:

Template Parameter	Description
file	The fax job file content (in case of template) or name (in case of resource or URL parameters)
target.address	The fax job target address
target.name	The fax job target name
sender.name	The fax job sender name
sender.fax.number	The fax job sender fax number
sender.email	The fax job sender email
fax.job.id	The fax job ID

In case there is no template defined for a certain fax action, this class will throw an UnsupportedOperationException exception.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.process.submit.template.command	The submit fax job template command.	none	none	false
org.fax4j.spi.process.suspend.template.command	The suspend fax job template command.	none	none	false
org.fax4j.spi.process.resume.template.command	The resume fax job template command.	none	none	false
org.fax4j.spi.process.cancel.template.command	The cancel fax job template command.	none	none	false
org.fax4j.spi.process.get.status.template.command	The get status fax job template command.	none	none	false
org.fax4j.spi.process.output.validator	The process output validator class name.	org.fax4j.spi.process.ExitCodeProcessOutputValidator	org.fax4j.spi.process.ExitCodeProcessOutputValidator	false
org.fax4j.spi.process.output.handler	The process output handler class name.	none	none	false
org.fax4j.spi.process.use.windows.command.prefix	True to add a windows command prefix to the command template.	false	false	false
org.fax4j.spi.process.windows.command.prefix	True to add a windows command prefix to the command template.	rundll32 SHELL32.DLL,ShellExec_RunDLL	rundll32 SHELL32.DLL,ShellExec_RunDLL	false

Dependencies:

External executable/script must be available

org.fax4j.spi.linux.LinuxFaxClientSpi

This implementation will proxy the requests to linux native fax commands.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.linux.submit.template.command	The linux submit fax job template command.	efax -d /dev/modem -t ${target.address} ${file}	none	true
org.fax4j.spi.linux.suspend.template.command	The suspend fax job template command.	none	none	false
org.fax4j.spi.linux.resume.template.command	The resume fax job template command.	none	none	false
org.fax4j.spi.linux.cancel.template.command	The cancel fax job template command.	none	none	false
org.fax4j.spi.linux.get.status.template.command	The get status fax job template command.	none	none	false
org.fax4j.spi.linux.output.validator	The process output validator class name.	org.fax4j.spi.process.ExitCodeProcessOutputValidator	org.fax4j.spi.process.ExitCodeProcessOutputValidator	false
org.fax4j.spi.linux.output.handler	The process output handler class name.	none	none	false

Limitations:

This SPI will only work on linux OS.

Dependencies:

Required linux efax utility.

org.fax4j.spi.mac.MacFaxClientSpi

This implementation will proxy the requests to mac native fax commands.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mac.submit.command	The submit fax job command	lp	lp	false
org.fax4j.spi.mac.print.queue.parameter	The print queue parameter	-d	-d	false
org.fax4j.spi.mac.print.queue.name	The print queue name	none	none	true
org.fax4j.spi.mac.general.parameters	The general parameters	-o	-o	false
org.fax4j.spi.mac.phone.parameter	The phone parameter	phone	phone	false
org.fax4j.spi.mac.fax.to.parameter	The fax to parameter	faxTo	faxTo	false

Limitations:

This SPI will only work on Mac OS.

org.fax4j.spi.hylafax.HylaFaxClientSpi

This implementation is based on the open source hylafax project.
It implements the hylafax protocol used by the open source hylafax fax server.
See http://sourceforge.net/projects/gnu-hylafax/ for more info.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.hylafax.connection.factory.class.name	The connection factory class name	org.fax4j.spi.hylafax.HylaFAXClientConnectionFactoryImpl	org.fax4j.spi.hylafax.HylaFAXClientConnectionFactoryImpl	false
org.fax4j.spi.hylafax.host	See gnu-hylafax project for more info.	none	none	true
org.fax4j.spi.hylafax.port	See gnu-hylafax project for more info.	none	gnu.hylafax.HylaFAXClientProtocol.DEFAULT_PORT	false
org.fax4j.spi.hylafax.user	See gnu-hylafax project for more info.	none	none	true
org.fax4j.spi.hylafax.password	See gnu-hylafax project for more info.	none	none	false
org.fax4j.spi.hylafax.admin	See gnu-hylafax project for more info.	false	false	false
org.fax4j.spi.hylafax.mode	See gnu-hylafax project for more info.	Z	none	true
org.fax4j.spi.hylafax.type	See gnu-hylafax project for more info.	A	none	true

Limitations:

See http://sourceforge.net/projects/gnu-hylafax/ web site.
Works only with HylaFax fax servers.

Dependencies:

Hylafax jar files (they are distributed as part of the fax4j, but required to be set in the application classpath)
See http://sourceforge.net/projects/gnu-hylafax/ web site.

org.fax4j.spi.comm.CommFaxClientSpi

This implementation will invoke the requests by sending the data via COMM ports to the fax modem.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.comm.port.name	The COMM port name (COM1, ...) property key	none	none	true
org.fax4j.spi.comm.connection.factory.class.name	The connection factory class name	org.fax4j.spi.comm.CommPortConnectionFactoryImpl	org.fax4j.spi.comm.CommPortConnectionFactoryImpl	false
org.fax4j.spi.comm.fax.modem.class.name	The fax modem class name	none	none	true
org.fax4j.spi.comm.connection.timeout	The timeout value when trying to own a COMM port	1500	1500	false

Limitations:

See the relevant COMM connection and fax modem documentation.

Dependencies:

See the relevant COMM connection and fax modem documentation.

org.fax4j.spi.http.HTTPFaxClientSpi

This implementation will invoke the requests by sending HTTP requests to a web server that supports sending fax messages.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.http.client.class.name	The HTTP client class name used to submit the HTTP requests	org.fax4j.spi.http.ApacheHTTPClient	org.fax4j.spi.http.ApacheHTTPClient	false
org.fax4j.spi.http.faxjob2request.converter.class.name	The fax job to HTTP request converter class name used to convert the fax job data into the relevant HTTP request.	org.fax4j.spi.http.MultiPartFaxJob2HTTPRequestConverter	org.fax4j.spi.http.MultiPartFaxJob2HTTPRequestConverter	false
org.fax4j.spi.http.response.handler.class.name	The HTTP response handler class name used to update the fax job data based on the HTTP response.	org.fax4j.spi.http.JSONHTTPResponseHandler	org.fax4j.spi.http.JSONHTTPResponseHandler	false
org.fax4j.spi.http.host.name	The target (service provider) host name.	none	none	true
org.fax4j.spi.http.port	The target port number.	none	none	false
org.fax4j.spi.http.ssl	True to use SSL (HTTPS), false for simple HTTP	false	false	false
org.fax4j.spi.http.submit.resource	The default HTTP resource of the submit fax job request	none	none	false
org.fax4j.spi.http.suspend.resource	The default HTTP resource of the suspend fax job request	none	none	false
org.fax4j.spi.http.resume.resource	The default HTTP resource of the resume fax job request	none	none	false
org.fax4j.spi.http.cancel.resource	The default HTTP resource of the cancel fax job request	none	none	false
org.fax4j.spi.http.get.status.resource	The default HTTP resource of the get fax job status request	none	none	false
org.fax4j.spi.http.url.parameters	The default HTTP URL parameters of the request	none	none	false
org.fax4j.spi.http.submit.method	The HTTP method for the submit action	POST	POST	false
org.fax4j.spi.http.suspend.method	The HTTP method for the suspend action	POST	POST	false
org.fax4j.spi.http.resume.method	The HTTP method for the resume action	POST	POST	false
org.fax4j.spi.http.cancel.method	The HTTP method for the cancel action	POST	POST	false
org.fax4j.spi.http.get.status.method	The HTTP method for the get fax job status action	POST	POST	false

org.fax4j.spi.http.faxjob2request.converter.class.name - org.fax4j.spi.http.MultiPartFaxJob2HTTPRequestConverter

This class will construct a multi part HTTP requests.
The parameter names are set in the fax4j configuration and their values are extracted from the fax job.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.http.multi.part.submit.file.content.parameter	The submit fax action, file content parameter name.	file	file	false
org.fax4j.spi.http.multi.part.submit.file.name.parameter	The submit fax action, file name parameter name.	filename	filename	false
org.fax4j.spi.http.multi.part.submit.target.address.parameter	The submit fax action, target address parameter name.	targetaddress	targetaddress	false
org.fax4j.spi.http.multi.part.submit.target.name.parameter	The submit fax action, target name parameter name.	targetname	targetname	false
org.fax4j.spi.http.multi.part.submit.sender.name.parameter	The submit fax action, sender name parameter name.	sendername	sendername	false
org.fax4j.spi.http.multi.part.submit.sender.fax.number.parameter	The submit fax action, sender fax number parameter name.	senderfaxnumber	senderfaxnumber	false
org.fax4j.spi.http.multi.part.submit.sender.email.parameter	The submit fax action, sender email parameter name.	senderemail	senderemail	false
org.fax4j.spi.http.multi.part.suspend.fax.job.id.parameter	The suspend fax action, fax job ID parameter name.	faxjobid	faxjobid	false
org.fax4j.spi.http.multi.part.resume.fax.job.id.parameter	The resume fax action, fax job ID parameter name.	faxjobid	faxjobid	false
org.fax4j.spi.http.multi.part.cancel.fax.job.id.parameter	The cancel fax action, fax job ID parameter name.	faxjobid	faxjobid	false
org.fax4j.spi.http.multi.part.get.status.fax.job.id.parameter	The get fax job status fax action, fax job ID parameter name.	faxjobid	faxjobid	false
org.fax4j.spi.http.multi.part.parameter.key.X	The additional parameter to submit where X is the parameter key and the property value is the parameter value, For example org.fax4j.spi.http.multi.part.parameter.key.my.property=my_value This converter will also send parameter my.property with value my_value	none	none	false
org.fax4j.spi.http.multi.part.add.file.name.as.part	The add the file name as a separate part property key.	true	true	false

org.fax4j.spi.http.faxjob2request.converter.class.name - org.fax4j.spi.http.TemplateFaxJob2HTTPRequestConverter

This class will use request templates to construct the HTTP requests.
Only the HTTP resource, URL parameters and HTTP content accept template parameters.
The HTTP resource is the URL part after the domain, for example http://www.mydomain.com/myresource.
The HTTP URL parameters is the URL part after the ?, for example http://www.mydomain.com/myresource?param1=value1.
The HTTP content is not part of the URL and contains the POST information.
The template parameters are than updated with the values from the fax4j configuration or FaxJob data.
All template parameters are defined as ${templatename} variables, for example: http://www.mydomain.com/myresource?faxnum=${target.address}

Below table describes the template parameters.
Template Parameters:

Template Parameter	Description
file	The fax job file content (in case of template) or name (in case of resource or URL parameters)
target.address	The fax job target address
target.name	The fax job target name
sender.name	The fax job sender name
sender.fax.number	The fax job sender fax number
sender.email	The fax job sender email

In case there is no template defined for a certain fax action, this class will return null.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.http.template.encoding	The template encoding, if encoding is not defined, the default system encoding is used.	none	The default system encoding	false
org.fax4j.spi.http.submit.template.url	The URL pointing to the submit fax job template.	none	none	false
org.fax4j.spi.http.suspend.template.url	The URL pointing to the suspend fax job template.	none	none	false
org.fax4j.spi.http.resume.template.url	The URL pointing to the resume fax job template.	none	none	false
org.fax4j.spi.http.cancel.template.url	The URL pointing to the cancel fax job template.	none	none	false
org.fax4j.spi.http.get.status.template.url	The URL pointing to the get fax job status template.	none	none	false

org.fax4j.spi.http.response.handler.class.name - org.fax4j.spi.http.JSONHTTPResponseHandler

This class provides a JSON based implementation of the HTTP response handler interface.
This class expects to get JSON response data and will update the fax job as needed.
This class only supports extracting the fax job ID and fax job status from the JSON response object, or in case of errors, extract the error message.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.http.response.data.encoding	The response data encoding, if encoding is not defined, the default system encoding is used.	none	The default system encoding	false
org.fax4j.spi.http.submit.json.output.path	The submit JSON output path used to locate the fax job ID from the submit fax job response.	none	none	false
org.fax4j.spi.http.suspend.json.output.path	The suspend JSON output path used to locate the fax job ID from the suspend fax job response.	none	none	false
org.fax4j.spi.http.resume.json.output.path	The resume JSON output path used to locate the fax job ID from the resume fax job response.	none	none	false
org.fax4j.spi.http.cancel.json.output.path	The cancel JSON output path used to locate the fax job ID from the cancel fax job response.	none	none	false
org.fax4j.spi.http.get.status.json.output.path	The get fax job status JSON output path used to locate the fax job status string value from the response.	none	none	false
org.fax4j.spi.http.json.pending.status.mappings	The mapping between the output fax status string value to the fax4j FaxJobStatus.PENDING enum value (format is: value1;value2;value3).	none	none	false
org.fax4j.spi.http.json.inprogress.status.mappings	The mapping between the output fax status string value to the fax4j FaxJobStatus.IN_PROGRESS enum value (format is: value1;value2;value3).	none	none	false
org.fax4j.spi.http.json.error.status.mappings	The mapping between the output fax status string value to the fax4j FaxJobStatus.ERROR enum value (format is: value1;value2;value3).	none	none	false
org.fax4j.spi.http.json.error.detection.path	The error detection path. If defined the handler will search for values in the defined path.	none	none	false
org.fax4j.spi.http.json.error.detection.value	If detection path and value are defined, the value in the path is searched within the configured value. If value is not defined, all values are considered as errors.	none	none	false
org.fax4j.spi.http.json.error.message.path	The path to the error message if errors are detected. If this property is not defined, the value found at org.fax4j.spi.http.json.error.detection.path will be used instead.	none	none	false

org.fax4j.spi.http.response.handler.class.name - org.fax4j.spi.http.XMLHTTPResponseHandler

This class provides a XML based implementation of the HTTP response handler interface.
This class expects to get XML response data and will update the fax job as needed.
This class only supports extracting the fax job ID and fax job status from the XML response object, or in case of errors, extract the error message.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.http.response.data.encoding	The response data encoding, if encoding is not defined, the default system encoding is used.	none	The default system encoding	false
org.fax4j.spi.http.submit.xml.output.path	The submit XML output path used to locate the fax job ID from the submit fax job response.	none	none	false
org.fax4j.spi.http.suspend.xml.output.path	The suspend XML output path used to locate the fax job ID from the suspend fax job response.	none	none	false
org.fax4j.spi.http.resume.xml.output.path	The resume XML output path used to locate the fax job ID from the resume fax job response.	none	none	false
org.fax4j.spi.http.cancel.xml.output.path	The cancel XML output path used to locate the fax job ID from the cancel fax job response.	none	none	false
org.fax4j.spi.http.get.status.xml.output.path	The get fax job status XML output path used to locate the fax job status string value from the response.	none	none	false
org.fax4j.spi.http.xml.pending.status.mappings	The mapping between the output fax status string value to the fax4j FaxJobStatus.PENDING enum value (format is: value1;value2;value3).	none	none	false
org.fax4j.spi.http.xml.inprogress.status.mappings	The mapping between the output fax status string value to the fax4j FaxJobStatus.IN_PROGRESS enum value (format is: value1;value2;value3).	none	none	false
org.fax4j.spi.http.xml.error.status.mappings	The mapping between the output fax status string value to the fax4j FaxJobStatus.ERROR enum value (format is: value1;value2;value3).	none	none	false
org.fax4j.spi.http.xml.error.detection.path	The error detection path. If defined the handler will search for values in the defined path.	none	none	false
org.fax4j.spi.http.xml.error.detection.value	If detection path and value are defined, the value in the path is searched within the configured value. If value is not defined, all values are considered as errors.	none	none	false
org.fax4j.spi.http.xml.error.message.path	The path to the error message if errors are detected. If this property is not defined, the value found at org.fax4j.spi.http.xml.error.detection.path will be used instead.	none	none	false

Dependencies:

HTTP client required jars (they are distributed as part of the fax4j, but required to be set in the application classpath).

org.fax4j.spi.interfax.InterfaxMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the interfax commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.nextivafax.NextivafaxMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the nextivafax commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.send2fax.Send2FaxMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the send2fax commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.metrofax.MetroFaxMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the MetroFax commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.faxage.FaxAgeMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the FaxAge commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.extremefax.ExtremeFaxMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the Extreme Fax commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.efax.EFaxMailFaxClientSpi

This implementation simply extends the MailFaxClientSpi and provides predefined configuration to support sending faxes via mail servers using the efax commercial service.
This implementation is not meant to promote the commercial service but to serve as a service provider interface for it.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.mail.persistent.connection	True to reuse the same mail connection for all fax activities, false to create a new mail connection for each fax activity.	false	false	false
org.fax4j.spi.mail.user.name	The mail account user name.	none	none	false
org.fax4j.spi.mail.password	The mail account password.	none	none	false
javax mail properties	Any of the javax mail properties can be defined in the fax4j properties. These properties will be passed to the java mail framework.	mail.transport.protocol=smtp mail.smtp.port=25	none	false

Limitations:

See MailFaxClientSpi SPI

Dependencies:

See MailFaxClientSpi SPI

org.fax4j.spi.phaxio.PhaxioFaxClientSpi

This class implements the fax client service provider interface.
This implementation will invoke the requests by sending HTTP requests to a Phaxio service.
This implementation is not meant to promote the Phaxio commercial product but to serve as a service provider interface for those using this product.

Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.phaxio.client.class.name	The HTTP client class name used to submit the HTTP requests	org.fax4j.spi.http.ApacheHTTPClient	org.fax4j.spi.http.ApacheHTTPClient	false
org.fax4j.spi.phaxio.api.key	The phaxio API key	none	none	true
org.fax4j.spi.phaxio.api.secret	The phaxio API secret	none	none	true

Dependencies:

HTTP client required jars.

org.fax4j.spi.hoiio.HoiioFaxClientSpi

This class implements the fax client service provider interface.
This implementation will invoke the requests by sending HTTP requests to a Hoiio service.
This implementation is not meant to promote the Hoiio commercial product but to serve as a service provider interface for those using this product.

Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.hoiio.client.class.name	The HTTP client class name used to submit the HTTP requests	org.fax4j.spi.http.ApacheHTTPClient	org.fax4j.spi.http.ApacheHTTPClient	false
org.fax4j.spi.hoiio.app.id	The hoiio Application ID	none	none	true
org.fax4j.spi.hoiio.access.token	The hoiio access token	none	none	true

Dependencies:

HTTP client required jars.

org.fax4j.spi.java4less.RFaxFaxClientSpi

This class implements the fax client service provider interface.
This implementation is based on the java4less commercial product.
This implementation is not meant to promote the java4less commercial product but to serve as a service provider interface for those using this product.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.spi.rfax.port.name	See java4less website for more info.	none	none	true
org.fax4j.spi.rfax.fax.class	See java4less website for more info.	none	none	true

Limitations:

See java4less web site.
Currently this SPI only supports submitting new fax jobs.

Dependencies:

See java4less web site.

The Fax Bridges:

The following section describes the fax4j built in fax bridges.

org.fax4j.bridge.email.EMail2FaxBridge

This interface defines the email2fax capabilities of the fax bridge.
Email based bridge would probably not have much information to provide the fax client and therefore has email specific bridge capabilities.

Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.bridge.vendor.policy.class.name	The vendor policy class name.	org.fax4j.bridge.EmptyVendorPolicy	org.fax4j.bridge.EmptyVendorPolicy	false
org.fax4j.bridge.mail.message.parser.class.name	The mail message parser class name used to convert the mail message to fax job data.	org.fax4j.bridge.email.DefaultMailMessageParser	org.fax4j.bridge.email.DefaultMailMessageParser	false

This default parser expects the mail message as follows:

Subject line: fax:[number] where number is the target address
From email address would be used as sender email
First attachment (or in case of none, the body text) would be used as the fax data

org.fax4j.bridge.http.HTTP2FaxBridge

This interface defines the http2fax capabilities of the fax bridge.
HTTP based bridges should be accessed by web servers via http servlet or similar.

Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.bridge.vendor.policy.class.name	The vendor policy class name.	org.fax4j.bridge.EmptyVendorPolicy	org.fax4j.bridge.EmptyVendorPolicy	false
org.fax4j.bridge.http.request.parser.class.name	The HTTP request parser class name used to convert the HTTP request to fax job data.	org.fax4j.bridge.http.MultiPartHTTPRequestParser	org.fax4j.bridge.http.MultiPartHTTPRequestParser	false

org.fax4j.bridge.http.request.parser.class.name - org.fax4j.bridge.http.MultiPartHTTPRequestParser

This parser expects a multi part HTTP request.
Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.bridge.http.request.parser.multi.part.file.content.parameter	The file content parameter name.	file	file	false
org.fax4j.bridge.http.request.parser.multi.part.file.name.parameter	The file name parameter name.	filename	filename	false
org.fax4j.bridge.http.request.parser.multi.part.priority.parameter	The priority parameter name.	priority	priority	false
org.fax4j.bridge.http.request.parser.multi.part.target.address.parameter	The target address parameter name.	targetaddress	targetaddress	false
org.fax4j.bridge.http.request.parser.multi.part.target.name.parameter	The target name parameter name.	targetname	targetname	false
org.fax4j.bridge.http.request.parser.multi.part.sender.name.parameter	The sender name parameter name.	sendername	sendername	false
org.fax4j.bridge.http.request.parser.multi.part.sender.fax.number.parameter	The sender fax number parameter name.	senderfaxnumber	senderfaxnumber	false
org.fax4j.bridge.http.request.parser.multi.part.sender.email.parameter	The sender email parameter name.	senderemail	senderemail	false

org.fax4j.bridge.http.request.parser.class.name - org.fax4j.bridge.http.SimpleHTTPRequestParser

This parser expects the HTTP request as follows:
URL parameters:

file [file name without path]
priority [priority value as defined in the enum]
target_address [target address]
target_name [target name]
sender_name [sender name]
sender_fax_number [sender fax number]
sender_email [sender email]
property:[property name] [property value]

The request Payload should hold the file content only.

org.fax4j.bridge.process.Process2FaxBridge

This interface defines the process2fax capabilities of the fax bridge.
Process based bridges can be exposed as standalone java applications.

Below table describes the configuration values relevant for this class.
Configuration:

Name	Description	Preconfigured Value	Default Value	Mandatory
org.fax4j.bridge.vendor.policy.class.name	The vendor policy class name.	org.fax4j.bridge.EmptyVendorPolicy	org.fax4j.bridge.EmptyVendorPolicy	false
org.fax4j.bridge.process.command.parser.class.name	The command line parser class name used to convert the command line arguments to fax job data.	org.fax4j.bridge.process.DefaultCommandLineArgumentsParser	org.fax4j.bridge.process.DefaultCommandLineArgumentsParser	false

The default command line arguments parser expects the command line arguments as follows:

-file [full file name]
-priority [priority value as defined in the enum]
-target_address [target address]
-target_name [target name]
-sender_name [sender name]
-sender_fax_number [sender fax number]
-sender_email [sender email]
-property:[property name] [property value]

Author:: Sagie Gur-Ari