org.fax4j.spi.vbs

Class VBSFaxClientSpi

java.lang.Object

org.fax4j.spi.AbstractFaxClientSpi

org.fax4j.spi.AbstractFax4JClientSpi

org.fax4j.spi.vbs.VBSFaxClientSpi

All Implemented Interfaces:

ConfigurationHolder, FaxClientActions, ProviderImplementation, FaxClientSpi

public class VBSFaxClientSpi
extends AbstractFax4JClientSpi

This class implements the fax client service provider interface.
This implementation will proxy the requests to VB scripts that will invoke the windows fax API.
It is highly recommanded 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.

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 preconfigured values for the fax4j framework and can be changed by updating these properties in the higher layers.
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.
These properties enable to override the configuration of the lower 2 layers.

SPI Status (Draft, Beta, Stable): Stable

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.

Since:

0.1

Version:

1.26

Author:

Sagie Gur-Ari

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VBSFaxClientSpi.FaxClientSpiConfigurationConstants This class holds the SPI configuration constants.
static class	VBSFaxClientSpi.FaxJobExtendedPropertyConstants This class holds the fax job extended properties.

Field Summary

Fields

Modifier and Type	Field and Description
protected String	faxServerName The fax server name
protected boolean	useWin2kAPI The use windows 2000 API flag
protected String	vbsExePath The VBS exe path
static String	WIN_2K_OS_NAME The windows 2000 OS name

Constructor Summary

Constructors

Constructor and Description
VBSFaxClientSpi() This is the default constructor.

Method Summary

Modifier and Type	Method and Description
protected void	cancelFaxJobImpl(FaxJob faxJob) This function will cancel an existing fax job.
protected Object	formatObject(Object object) This function formats the provided object to enable embedding in VBS code.
protected String	generateScript(String name, Object[] input) This function generates the script and returns it.
protected FaxJobStatus	getFaxJobStatusImpl(FaxJob faxJob) This function returns the fax job status. Not all SPIs support extraction of the fax job status. In case the SPI is unable to extract or does not support extracting of the fax job status, it will return the UNKNOWN status.
protected String	getVBSExePath() This function return the VBS exe path.
protected void	initializeImpl() This function initializes the fax client SPI.
protected FaxJobStatus	invokeExistingFaxJobAction(String scriptName, FaxJob faxJob, FaxActionType faxActionType) Invokes a basic fax action
protected FaxJobStatus	invokeScript(FaxJob faxJob, String name, Object[] input, FaxActionType faxActionType) Invokes the VB script and returns its output.
protected ProcessExecutorHelper.ProcessOutput	invokeScript(String script) Invokes the VB script and returns the output.
boolean	isFaxMonitorEventsSupported() This function returns true if the fax monitor events are supported by this SPI.
protected void	resumeFaxJobImpl(FaxJob faxJob) This function will resume an existing fax job.
protected Object[]	setupSubmitFaxJobInput(FaxJob faxJob) This function creates an input array with the needed info to submit a new fax job based on the provided data.
protected void	submitFaxJobImpl(FaxJob faxJob) This function will submit a new fax job. The fax job ID may be populated by this method in the provided fax job object.
protected void	suspendFaxJobImpl(FaxJob faxJob) This function will suspend an existing fax job.

Methods inherited from class org.fax4j.spi.AbstractFax4JClientSpi

getProvider, pollForFaxJobStatues, pollForFaxJobStatuesImpl

Methods inherited from class org.fax4j.spi.AbstractFaxClientSpi

addFaxClientActionEventListener, addFaxMonitorEventListener, cancelFaxJob, createFaxJob, createFaxJobImpl, fireFaxEvent, fireFaxEvent, fireFaxMonitorEvent, getConfiguration, getConfigurationValue, getConfigurationValue, getFaxJobMonitor, getFaxJobStatus, getLogger, getPropertyPart, initialize, invokeFaxJobIDValidation, invokeFaxJobNullValidation, removeAllFaxClientActionEventListeners, removeAllFaxMonitorEventListeners, removeFaxClientActionEventListener, removeFaxMonitorEventListener, resumeFaxJob, submitFaxJob, suspendFaxJob, throwUnsupportedException

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

faxServerName

protected String faxServerName

The fax server name

vbsExePath

protected String vbsExePath

The VBS exe path

useWin2kAPI

protected boolean useWin2kAPI

The use windows 2000 API flag

WIN_2K_OS_NAME

public static final String WIN_2K_OS_NAME

The windows 2000 OS name

See Also:

Constant Field Values

Constructor Detail

VBSFaxClientSpi

public VBSFaxClientSpi()

This is the default constructor.

Method Detail

initializeImpl

protected void initializeImpl()

This function initializes the fax client SPI.

Specified by:

initializeImpl in class AbstractFaxClientSpi

isFaxMonitorEventsSupported

public boolean isFaxMonitorEventsSupported()

This function returns true if the fax monitor events are supported by this SPI.

Specified by:

isFaxMonitorEventsSupported in interface FaxClientSpi

Overrides:

isFaxMonitorEventsSupported in class AbstractFax4JClientSpi

Returns:

True if the fax monitor events are supported by this SPI

getVBSExePath

protected String getVBSExePath()

This function return the VBS exe path.

Returns:

The VBS exe path

submitFaxJobImpl

protected void submitFaxJobImpl(FaxJob faxJob)

This function will submit a new fax job.
The fax job ID may be populated by this method in the provided fax job object.

Overrides:

submitFaxJobImpl in class AbstractFax4JClientSpi

Parameters:

faxJob - The fax job object containing the needed information

suspendFaxJobImpl

protected void suspendFaxJobImpl(FaxJob faxJob)

This function will suspend an existing fax job.

Overrides:

suspendFaxJobImpl in class AbstractFax4JClientSpi

Parameters:

faxJob - The fax job object containing the needed information

resumeFaxJobImpl

protected void resumeFaxJobImpl(FaxJob faxJob)

This function will resume an existing fax job.

Overrides:

resumeFaxJobImpl in class AbstractFax4JClientSpi

Parameters:

faxJob - The fax job object containing the needed information

cancelFaxJobImpl

protected void cancelFaxJobImpl(FaxJob faxJob)

This function will cancel an existing fax job.

Overrides:

cancelFaxJobImpl in class AbstractFax4JClientSpi

Parameters:

faxJob - The fax job object containing the needed information

getFaxJobStatusImpl

protected FaxJobStatus getFaxJobStatusImpl(FaxJob faxJob)

This function returns the fax job status.
Not all SPIs support extraction of the fax job status.
In case the SPI is unable to extract or does not support extracting of the fax job status, it will return the UNKNOWN status.

Overrides:

getFaxJobStatusImpl in class AbstractFax4JClientSpi

Parameters:

faxJob - The fax job object containing the needed information

Returns:

The fax job status

setupSubmitFaxJobInput

protected Object[] setupSubmitFaxJobInput(FaxJob faxJob)

This function creates an input array with the needed info to submit a new fax job based on the provided data.

Parameters:

faxJob - The fax job object containing the needed information

Returns:

The submit fax job script input

formatObject

protected Object formatObject(Object object)

This function formats the provided object to enable embedding in VBS code.

Parameters:

object - The object to format

Returns:

The formatted object

invokeExistingFaxJobAction

protected FaxJobStatus invokeExistingFaxJobAction(String scriptName,
                                                  FaxJob faxJob,
                                                  FaxActionType faxActionType)

Invokes a basic fax action

Parameters:

scriptName - The script name

faxJob - The fax job object containing the needed information

faxActionType - The fax action type

Returns:

The fax job status (only for get fax job status action, for others null will be returned)

invokeScript

protected FaxJobStatus invokeScript(FaxJob faxJob,
                                    String name,
                                    Object[] input,
                                    FaxActionType faxActionType)

Invokes the VB script and returns its output.

Parameters:

faxJob - The fax job object containing the needed information

name - The script name

input - The script input

faxActionType - The fax action type

Returns:

The fax job status (only for get fax job status action, for others null will be returned)

invokeScript

protected ProcessExecutorHelper.ProcessOutput invokeScript(String script)

Invokes the VB script and returns the output.

Parameters:

script - The script to invoke

Returns:

The script output

generateScript

protected String generateScript(String name,
                                Object[] input)

This function generates the script and returns it.

Parameters:

name - The script name

input - The script input

Returns:

The formatted script