Package de.gmxhome.conrad.jpos.jpos_base.hardtotals

Interface HardTotalsInterface

All Superinterfaces:

JposBaseInterface

All Known Implementing Classes:

HardTotalsProperties

public interface HardTotalsInterface
extends JposBaseInterface

Interface for methods that implement property setter and method calls for the HardTotals device category. For details about properties, methods and method parameters, see UPOS specification, chapter Hard Totals. Further details about error handling can be found in introduction - Device Behavior Models - Errors.

Method Summary

Modifier and Type	Method	Description
void	beginTrans()	Final part of BeginTrans method.
void	claimFile(int hTotalsFile, int timeout)	Final part of ClaimFile method.
void	commitTrans()	Final part of CommitTrans method.
void	create(String fileName, int[] hTotalsFile, int size, boolean errorDetection)	Final part of Create method.
void	delete(String fileName)	Final part of Delete method.
void	find(String fileName, int[] hTotalsFile, int[] size)	Final part of Find method.
void	findByIndex(int index, String[] fileName)	Final part of FindByIndex method.
void	read(int hTotalsFile, byte[] data, int offset, int count, List<ChangeRequest> transaction)	Final part of Read method.
void	recalculateValidationData(int hTotalsFile)	Final part of RecalculateValidationData method.
void	releaseFile(int hTotalsFile)	Final part of ReleaseFile method.
void	rename(int hTotalsFile, String fileName)	Final part of Rename method.
void	rollback()	Final part of Rollback method.
SetAll	setAll(int hTotalsFile, byte value)	Validation part of SetAll method.
void	setAll(SetAll request)	Final part of SetAll method.
void	validateData(int hTotalsFile)	Final part of OpenGate method.
Write	write(int hTotalsFile, byte[] data, int offset, int count)	Validation part of Write method.
void	write(Write request)	Final part of Write method.

Methods inherited from interface de.gmxhome.conrad.jpos.jpos_base.JposBaseInterface

asyncMode, autoDisable, checkHealth, claim, clearInput, clearOutput, close, compareFirmwareVersion, dataEventEnabled, deviceEnabled, directIO, directIO, flagWhenIdle, freezeEvents, handlePowerStateOnEnable, newJposOutputRequest, open, powerNotify, release, removeFromPropertySetList, resetStatistics, retrieveStatistics, retryInput, retryOutput, unitDataCount, updateFirmware, updateFirmware, updateStatistics

Method Details

beginTrans

void beginTrans()
         throws jpos.JposException

Final part of BeginTrans method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• CapTransaction is true,
• TransactionInProgress is false.

Keep in mind that TransactionInProgress must be set to true after successful transaction begin. This can be done using the implementation in class HardTotalsProperties.

Throws:

jpos.JposException - If an error occurs.

claimFile

void claimFile(int hTotalsFile,
 int timeout)
        throws jpos.JposException

Final part of ClaimFile method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• The hard totals file specified by hTotalsFile has not been claimed previously,
• timeout is FOREVER or positive.

If the service must wait for a release from another instance and timeout is not FOREVER, timeout will be reduced by the number of milliseconds the service must wait to get exclusive access. If the service cannot get exclusive access, a JposException with error code E_TIMEOUT will be thrown without calling this method.

Parameters:

hTotalsFile - Handle of a totals file.

timeout - The (reduced) time in milliseconds to wait for the file to become available.

Throws:

jpos.JposException - If an error occurs.

commitTrans

void commitTrans()
          throws jpos.JposException

Final part of CommitTrans method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• CapTransactions is true,
• TransactionInProgress is true,
• All files used in stored Write or SetAll operations have not been claimed by another instance.

The ChangeRequest instances to be processed can be found in property Transaction.

Throws:

jpos.JposException - If an error occurs.

create

void create(String fileName,
 int[] hTotalsFile,
 int size,
 boolean errorDetection)
     throws jpos.JposException

Final part of Create method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• if CapSingleFile is true, fileName is an empty string,
• otherwise, fileName consists of no more than 10 ASCII characters (character codes between 0x20 and 0x7f,
• hTotalsFile is an array with length = 1,
• size is a positive value.

Parameters:

fileName - Name of totals file.

hTotalsFile - No matter on call, handle to file on return.

size - Requested size of the file.

errorDetection - Error detection level.

Throws:

jpos.JposException - If an error occurs.

delete

void delete(String fileName)
     throws jpos.JposException

Final part of Delete method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• if CapSingleFile is true, fileName is an empty string,
• otherwise, fileName consists of no more than 10 ASCII characters (character codes between 0x20 and 0x7f.

Keep in mind: This method must check whether the specified file has been claimed by another instance.

Parameters:

fileName - Name of file to be deleted.

Throws:

jpos.JposException - If an error occurs.

find

void find(String fileName,
 int[] hTotalsFile,
 int[] size)
   throws jpos.JposException

Final part of Find method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• if CapSingleFile is true, fileName is an empty string,
• otherwise, fileName consists of no more than 10 ASCII characters (character codes between 0x20 and 0x7f,
• hTotalsFile is an array with length = 1,
• size is an array with length = 1.

Parameters:

fileName - Name of file to be found.

hTotalsFile - No matter on call, file handle on return.

size - No matter on call, file size on return.

Throws:

jpos.JposException - If an error occurs.

findByIndex

void findByIndex(int index,
 String[] fileName)
          throws jpos.JposException

Final part of FindByIndex method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• fileName is an array with length = 1,
• index is ≥ 0 and < NumberOfFiles.

Parameters:

index - File index between 0 and NumberOfFiles - 1.

fileName - No matter on call, file name on return.

Throws:

jpos.JposException - If an error occurs.

read

void read(int hTotalsFile,
 byte[] data,
 int offset,
 int count,
 List<ChangeRequest> transaction)
   throws jpos.JposException

Final part of Read method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• offset ≥ 0, count ≥ 0 and length of data ≥ count,
• offset + count ≤ TotalsSize,
• The hard totals file specified by hTotalsFile has not been claimed by another instance.

The list of ChangeRequest objects passed via transaction consists of stored Write and SetAll requests stored due to transaction processing for the given file. The contents of these objects can be used to modify data read to get the expected results, if necessary. However, after a transaction ends in one instance of the service, remaining operations of other transactions can lead to a different read result whenever a previously buffered operation will be committed later, resulting in not being overwritten by the finished transaction.

Parameters:

hTotalsFile - Handle of a totals file.

data - Data buffer for read.

offset - Starting offset for read operation.

count - Number of bytes to be read.

transaction - List of ChangeRequest objects stored within all current transactions. An empty list if no transaction is in progress.

Throws:

jpos.JposException - If an error occurs.

recalculateValidationData

void recalculateValidationData(int hTotalsFile)
                        throws jpos.JposException

Final part of RecalculateValidationData method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• The hard totals file specified by hTotalsFile has not been claimed by other instance,
• Device supports advanced error detection.

Parameters:

hTotalsFile - Handle of a totals file.

Throws:

jpos.JposException - If an error occurs.

releaseFile

void releaseFile(int hTotalsFile)
          throws jpos.JposException

Final part of ReleaseFile method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• The hard totals file specified by hTotalsFile has not been claimed.

Parameters:

hTotalsFile - Handle of a totals file.

Throws:

jpos.JposException - If an error occurs.

rename

void rename(int hTotalsFile,
 String fileName)
     throws jpos.JposException

Final part of Rename method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• if CapSingleFile is true, fileName is an empty string,
• otherwise, fileName consists of no more than 10 ASCII characters (character codes between 0x20 and 0x7f,
• The hard totals file specified by hTotalsFile has not been claimed by other instance.

Parameters:

hTotalsFile - Handle of a totals file.

fileName - New file name.

Throws:

jpos.JposException - If an error occurs.

rollback

void rollback()
       throws jpos.JposException

Final part of Rollback method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled,
• CapTransactions and TransactionInProgress are true.

Throws:

jpos.JposException - If an error occurs.

validateData

void validateData(int hTotalsFile)
           throws jpos.JposException

Final part of OpenGate method. Can be overwritten in derived class, if necessary. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• The hard totals file specified by hTotalsFile has not been claimed by other instance,
• Device supports advanced error detection.

Parameters:

hTotalsFile - Handle of a totals file.

Throws:

jpos.JposException - If an error occurs.

setAll

SetAll setAll(int hTotalsFile,
 byte value)
       throws jpos.JposException

Validation part of SetAll method. Can be overwritten within derived classes, if necessary. This method shall only perform additional validation. It will be called before the service buffers the method call for synchronous or asynchronous execution. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• The hard totals file specified by hTotalsFile has not been claimed by another instance.

Parameters:

hTotalsFile - Handle of a totals file.

value - Value to set all locations to in totals file.

Returns:

SetAll object for use in final part or in CommitTrans.

Throws:

jpos.JposException - If an error occurs.

setAll

void setAll(SetAll request)
     throws jpos.JposException

Final part of SetAll method. Can be overwritten within derived classes, if necessary. The parameters of the method will be passed via a SetAll object. This method will be called when the corresponding operation shall be performed, either synchronously during commit. All plausibility checks have been made before, only runtime errors can occur.
The default implementation should be called within derived methods to ensure that the property TransactionInProgress is updated as expected.

Parameters:

request - Output request object returned by validation method that contains all parameters to be used by SetAll.

Throws:

jpos.JposException - If an error occurs.

write

Write write(int hTotalsFile,
 byte[] data,
 int offset,
 int count)
     throws jpos.JposException

Validation part of Write method. Can be overwritten within derived classes, if necessary. This method shall only perform additional validation. It will be called before the service buffers the method call for synchronous or asynchronous execution. This method will be called only if the following plausibility checks lead to a positive result:

• Device is enabled and not claimed by other instance,
• The byte buffer consists of at least count bytes,
• Both, offset and count, are ≥ 0 and their sum is %le; TotalsSize,
• Device has not been claimed by another instance,
• The hard totals file specified by hTotalsFile has not been claimed by another instance.

Parameters:

hTotalsFile - Handle of a totals file.

data - Data to be written.

offset - Starting offset for write operation.

count - Number of bytes to be written.

Returns:

Write object for use in final part.

Throws:

jpos.JposException - If an error occurs.

write

void write(Write request)
    throws jpos.JposException

Final part of Write method. Can be overwritten within derived classes, if necessary. The parameters of the method will be passed via a Write object. This method will be called when the corresponding operation shall be performed, either synchronously during commit. All plausibility checks have been made before, only runtime errors can occur.
The default implementation should be called within derived methods to ensure that the property TransactionInProgress is updated as expected.

Parameters:

request - Output request object returned by validation method that contains all parameters to be used by Write.

Throws:

jpos.JposException - If an error occurs.