ProcessFaxClientSpi (fax4j 0.45.0 API)

java.lang.Object
- org.fax4j.spi.AbstractFaxClientSpi
- - org.fax4j.spi.AbstractFax4JClientSpi
  - - org.fax4j.spi.process.ProcessFaxClientSpi

All Implemented Interfaces:: ConfigurationHolder, FaxClientActions, ProviderImplementation, FaxClientSpi

Direct Known Subclasses:: LinuxFaxClientSpi, WindowsProcessFaxClientSpi

public class ProcessFaxClientSpi
extends AbstractFax4JClientSpi

This class implements the fax client service provider interface.
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 path
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 throw an UnsupportedOperationException exception.

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

Since:: 0.21e
Version:: 1.13
Author:: Sagie Gur-Ari

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class ProcessFaxClientSpi.FaxClientSpiConfigurationConstants
This class holds the SPI configuration constants.
- Nested classes/interfaces inherited from class org.fax4j.spi.AbstractFaxClientSpi
  AbstractFaxClientSpi.FaxJobExtendedPropertyConstants

Nested Classes
Modifier and Type	Class and Description
`static class`	`ProcessFaxClientSpi.FaxClientSpiConfigurationConstants` This class holds the SPI configuration constants.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`useWindowsCommandPrefix` The use windows command prefix flag
`protected static String`	`WINDOWS_EXECUTE_PREFIX_DEFAULT_VALUE` The windows execute prefix

Constructor Summary

Constructors
Constructor and Description

ProcessFaxClientSpi()
This is the default constructor.

Constructors
Constructor and Description
`ProcessFaxClientSpi()` This is the default constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`cancelFaxJobImpl(FaxJob faxJob)` This function will cancel an existing fax job.
`protected String`	`createCancelFaxJobProcessCommand(FaxJob faxJob)` Creates the process command from the fax job data.
`protected String`	`createGetStatusFaxJobProcessCommand(FaxJob faxJob)` Creates the process command from the fax job data.
`protected String`	`createProcessCommand(Enum<?> templateNameEnum, FaxJob faxJob)` Creates the process command from the fax job data.
`protected ProcessOutputHandler`	`createProcessOutputHandler()` This function creates and returns the process output handler.
`protected ProcessOutputValidator`	`createProcessOutputValidator()` This function creates and returns the process output validator.
`protected String`	`createResumeFaxJobProcessCommand(FaxJob faxJob)` Creates the process command from the fax job data.
`protected String`	`createSubmitFaxJobProcessCommand(FaxJob faxJob)` Creates the process command from the fax job data.
`protected String`	`createSuspendFaxJobProcessCommand(FaxJob faxJob)` Creates the process command from the fax job data.
`protected ProcessExecutorHelper.ProcessOutput`	`executeProcess(FaxJob faxJob, String command, FaxActionType faxActionType)` Executes the process and returns the output.
`protected String`	`formatTemplate(String template, FaxJob faxJob)` This function formats the provided template.
`protected FaxJobStatus`	`getFaxJobStatus(ProcessExecutorHelper.ProcessOutput processOutput)` This function extracts the fax job status from the process output.
`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 ProcessOutputHandler`	`getProcessOutputHandler()` This function returns the process output handler.
`ProcessOutputValidator`	`getProcessOutputValidator()` This function returns the process output validator.
`String`	`getPropertyPart()` Returns the property part. Property parts enables to replace the input request key with the part defined to enable to reuse services with different configuration blocks. Property parts will be replaced with the {0} values in the key, for example org.fax4j.{0}.somekey with part abc will be replaced to org.fax4j.abc.somekey
`protected String`	`getTemplate(String templateName)` This function returns the template for the given template name.
`protected void`	`initializeImpl()` This function initializes the fax client SPI.
`protected void`	`resumeFaxJobImpl(FaxJob faxJob)` This function will resume an existing fax job.
`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.
`protected void`	`updateFaxJob(FaxJob faxJob, ProcessExecutorHelper.ProcessOutput processOutput, FaxActionType faxActionType)` Updates the fax job based on the data from the process output.
`protected void`	`validateProcessOutput(ProcessExecutorHelper.ProcessOutput processOutput, FaxActionType faxActionType)` This function validates the process output for errors. If not valid, an exception should be thrown.

Methods inherited from class org.fax4j.spi.AbstractFax4JClientSpi
getProvider, isFaxMonitorEventsSupported, pollForFaxJobStatues, pollForFaxJobStatuesImpl

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - useWindowsCommandPrefix
```
protected boolean useWindowsCommandPrefix
```
    The use windows command prefix flag
  - WINDOWS_EXECUTE_PREFIX_DEFAULT_VALUE
```
protected static final String WINDOWS_EXECUTE_PREFIX_DEFAULT_VALUE
```
    The windows execute prefix
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ProcessFaxClientSpi
```
public ProcessFaxClientSpi()
```
    This is the default constructor.
- Method Detail
  - initializeImpl
```
protected void initializeImpl()
```
    This function initializes the fax client SPI.
    
    Specified by:
    
    initializeImpl in class AbstractFaxClientSpi
  - getPropertyPart
```
public String getPropertyPart()
```
    Returns the property part.
    Property parts enables to replace the input request key with the part defined to enable to reuse services with different configuration blocks.
    Property parts will be replaced with the {0} values in the key, for example org.fax4j.{0}.somekey with part abc will be replaced to org.fax4j.abc.somekey
    
    Specified by:
    
    getPropertyPart in interface ConfigurationHolder
    
    Overrides:
    
    getPropertyPart in class AbstractFaxClientSpi
    
    Returns:
    
    The property part
  - createProcessOutputValidator
```
protected ProcessOutputValidator createProcessOutputValidator()
```
    This function creates and returns the process output validator.
    
    Returns:
    
    The process output validator
  - createProcessOutputHandler
```
protected ProcessOutputHandler createProcessOutputHandler()
```
    This function creates and returns the process output handler.
    
    Returns:
    
    The process output handler
  - getProcessOutputValidator
```
public final ProcessOutputValidator getProcessOutputValidator()
```
    This function returns the process output validator.
    
    Returns:
    
    The process output validator
  - getProcessOutputHandler
```
protected final ProcessOutputHandler getProcessOutputHandler()
```
    This function returns the process output handler.
    
    Returns:
    
    The process output handler
  - 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
  - getFaxJobStatus
```
protected FaxJobStatus getFaxJobStatus(ProcessExecutorHelper.ProcessOutput processOutput)
```
    This function extracts the fax job status from the process output.
    
    Parameters:
    
    processOutput - The process output
    
    Returns:
    
    The fax job status
  - executeProcess
```
protected ProcessExecutorHelper.ProcessOutput executeProcess(FaxJob faxJob,
                                                             String command,
                                                             FaxActionType faxActionType)
```
    Executes the process and returns the output.
    
    Parameters:
    
    faxJob - The fax job object
    
    command - The command to execute
    
    faxActionType - The fax action type
    
    Returns:
    
    The process output
  - formatTemplate
```
protected String formatTemplate(String template,
                                FaxJob faxJob)
```
    This function formats the provided template.
    
    Parameters:
    
    template - The template
    
    faxJob - The fax job object
    
    Returns:
    
    The formatted template
  - getTemplate
```
protected String getTemplate(String templateName)
```
    This function returns the template for the given template name.
    
    Parameters:
    
    templateName - The template name
    
    Returns:
    
    The template
  - createProcessCommand
```
protected String createProcessCommand(Enum<?> templateNameEnum,
                                      FaxJob faxJob)
```
    Creates the process command from the fax job data.
    
    Parameters:
    
    templateNameEnum - The template name
    
    faxJob - The fax job object
    
    Returns:
    
    The process command to execute
  - validateProcessOutput
```
protected void validateProcessOutput(ProcessExecutorHelper.ProcessOutput processOutput,
                                     FaxActionType faxActionType)
```
    This function validates the process output for errors.
    If not valid, an exception should be thrown.
    
    Parameters:
    
    processOutput - The process output to validate
    
    faxActionType - The fax action type
  - updateFaxJob
```
protected void updateFaxJob(FaxJob faxJob,
                            ProcessExecutorHelper.ProcessOutput processOutput,
                            FaxActionType faxActionType)
```
    Updates the fax job based on the data from the process output.
    
    Parameters:
    
    faxJob - The fax job object
    
    processOutput - The process output
    
    faxActionType - The fax action type
  - createSubmitFaxJobProcessCommand
```
protected String createSubmitFaxJobProcessCommand(FaxJob faxJob)
```
    Creates the process command from the fax job data.
    
    Parameters:
    
    faxJob - The fax job object
    
    Returns:
    
    The process command to execute
  - createSuspendFaxJobProcessCommand
```
protected String createSuspendFaxJobProcessCommand(FaxJob faxJob)
```
    Creates the process command from the fax job data.
    
    Parameters:
    
    faxJob - The fax job object
    
    Returns:
    
    The process command to execute
  - createResumeFaxJobProcessCommand
```
protected String createResumeFaxJobProcessCommand(FaxJob faxJob)
```
    Creates the process command from the fax job data.
    
    Parameters:
    
    faxJob - The fax job object
    
    Returns:
    
    The process command to execute
  - createCancelFaxJobProcessCommand
```
protected String createCancelFaxJobProcessCommand(FaxJob faxJob)
```
    Creates the process command from the fax job data.
    
    Parameters:
    
    faxJob - The fax job object
    
    Returns:
    
    The process command to execute
  - createGetStatusFaxJobProcessCommand
```
protected String createGetStatusFaxJobProcessCommand(FaxJob faxJob)
```
    Creates the process command from the fax job data.
    
    Parameters:
    
    faxJob - The fax job object
    
    Returns:
    
    The process command to execute

Class ProcessFaxClientSpi

Nested Class Summary

Nested classes/interfaces inherited from class org.fax4j.spi.AbstractFaxClientSpi

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.fax4j.spi.AbstractFax4JClientSpi

Methods inherited from class org.fax4j.spi.AbstractFaxClientSpi

Methods inherited from class java.lang.Object

Field Detail

useWindowsCommandPrefix

WINDOWS_EXECUTE_PREFIX_DEFAULT_VALUE

Constructor Detail

ProcessFaxClientSpi

Method Detail

initializeImpl

getPropertyPart

createProcessOutputValidator

createProcessOutputHandler

getProcessOutputValidator

getProcessOutputHandler

submitFaxJobImpl

suspendFaxJobImpl

resumeFaxJobImpl

cancelFaxJobImpl

getFaxJobStatusImpl

getFaxJobStatus

executeProcess

formatTemplate

getTemplate

createProcessCommand

validateProcessOutput

updateFaxJob

createSubmitFaxJobProcessCommand

createSuspendFaxJobProcessCommand

createResumeFaxJobProcessCommand

createCancelFaxJobProcessCommand

createGetStatusFaxJobProcessCommand