Package SampleCAT

Class Device

java.lang.Object
de.gmxhome.conrad.jpos.jpos_base.JposBaseDevice
de.gmxhome.conrad.jpos.jpos_base.JposDevice
SampleCAT.Device
All Implemented Interfaces:
Runnable
public class Device extends JposDevice implements Runnable
Base of a JposDevice based implementation of JavaPOS CAT and ElectronicJournal device service implementations for the sample device implemented in SampleCAT.tcl. The sample device simulates EFT payment transactions without ticket printing (the simulator sends ticket and display data to its target).
Supported features are:
  • Sale, refund and void.
  • Start transaction before amount to approve is known.
  • Confirmation in case of signature based approval.
  • Lock / unlock terminal.
  • Card issuer, transaction number, transaction date, tip, approved amount, approval result, terminal result, masked card number (last 4 digit readable), expiration date sent in case of successful operation.
  • Display output will be sent to LineDisplay or to the application via DirectIOEvent during CAT operations.
  • Ticket layout will be send to a POS printer, to the application via DirectIOEvent or passed to ElectronicJournal devices.
DisplayName is a mandatory property in Jpos.xml. If not specified or not empty, it must specify the name of a LineDisplay device that shall be used to echo the contents of the terminal display. It will be working best if it has 4 x 40 characters or more, a minimum of 2 x 20 is recommended.
Minimum requirements: It must support code mapping or ASCII, ANSI or Unicode encoding.
The advantages of processing display data via DirectIOEvent:
  • The application has full control over display contents.
  • No hardware limits for number of display lines and columns (sample CAT uses 4 lines with 40 characters).
  • No limitations for test formatting, character sets and usable fonts.
  • Neither need to release the cash register's LineDisplay before CAT operations nor need to re-claim and re-enable the LineDisplay after CAT operation has been finished.
The advantages of sending display data to LineDisplay device:
  • No need for vendor-specific code to process display data.
  • No need to change the application if it is designed to share its line display during CAT operations:
    • If the application releases the LineDisplay before CAT operations start.
    • If the application re-claims and re-enables LineDisplay after CAT operations finish.
JournalPath is a mandatory property in Jpos.xml. It can specify the name of a POSPrinter device that shall be used to print ticket data, a prefix for customer and merchant journals or it can be empty.
If JournalPath specifies a POSPrinter device name, the printer will be claimed and enabled at CAT operation start. If the printer reports an error (not online, paper near end, cover open), the CAT operation will not be started. If printing ticket data fails due to head cleaning, printing will be repeated automatically, otherwise the sample waits for pressing the OK button on a message box (OK, that's a bad solution, but this is only a sample). After printing finished, the POSPrinter will be released.
Minimum requirements to the POSPrinter device:
  • Power Reporting,
  • Receipt print station,
  • Receipt near end sensor,
  • Maximum receipt width ≥ JournalWidth (Jpos.xml) property. Default for JournalWidth is 32.
If JournalPath specifies a path prefix (the service appends either ".merchant.tickets" or ".customer.tickets"), ticket data will be written to one or two of two virtual ElectronicJournal devices: The device with Jpos.xml property DevIndex = 0 for customer tickets, the device with DevIndex = 1 for merchant tickets. After each sales transaction, the application cat query the full layouted tickets for customer and (if present) for merchant from the corresponding ElectronicJournal devices as described in the UPOS manual, merge them into the sales receipt or print them separately and optionally clear the journals after processing, once a day of whenever nearly full. If JournalPath is empty, ticket data will be passed to the application via DirectIOEvent. Even if the way the application gets the tickets for customer and merchant is different, processing ticket data can be similar to the ElectronicJournal scenario.
Ticket data of the sample CAT do not contain any control characters except newline (0ah).
The advantages of processing ticket data via DirectIOEvent:
  • Printing ticket data is completely under control of the application, including error handling and error recovery.
  • The application knows the ticket data and can print copies if requested.
  • Ticket data come directly from the service to the application, no need to query data from ElectronicJournal devices.
  • No need to release the POSPrinter before each CAT operation and to re-claim and re-enable after each CAT operation has been finished.
The advantages of processing data via ElectronicJournal devices:
  • Printing ticket data is completely under control of the application, including error handling and error recovery.
  • The application knows the ticket data and can print copies if requested.
  • The ElectronicJournal interface is a well-defined standard, no vendor specific implementation needed (if usage of ElectronicJournal devices has been implemented for such usage cases).
  • No need to release the POSPrinter before each CAT operation and to re-claim and re-enable after each CAT operation has been finished.
The advantages of sending ticket data directly to POSPrinter:
  • No need for vendor-specific code to process ticket data.
  • No need to change the application if it is designed to share its pos printer during CAT operations:
    • If the application releases the POSPrinter before CAT operations start.
    • If the application re-claims and re-enables POSPrinter after CAT operations finish.
    This implies that the application uses only subsequent receipt printing because the sales receipt cannot be finished before payment operations have been finished (CAT operations are payment operations) and ticket printing would destroy the sales receipt otherwise. receipt.

Here a full list of all device specific properties that can be changed via jpos.xml:
  • CharacterTimeout: Positive integer value, specifying the maximum delay between bytes that belong to the same frame. Default value: 50 milliseconds.
  • ClientPort: Integer value between 0 and 65535 specifying the TCP port used for communication with the device simulator. Default: 0 (for random port number selected by operating system).
  • DisplayLines: Number of display lines the application or the attached JavaPOS display can support. Must be 2, 3 or 4. Default: 4
  • DisplayName: See description above: Must be a LineDisplay device name or empty. Default: empty.
  • DisplayWidth: Maximum length of a single display line the application or the attached LineDisplay can support. Must be an integer value between 20 and 40 (both inclusive). Default: 40.
  • JournalLowSize: Maximum free space (in tickets) to report nearly full. Must be a positive value between 0 and the maximum size of the journal, in tickets. Default: 10.
  • JournalMaxSize: Maximum size of of electronic journal (in tickets). Must be a positive value. Default: 1000.
  • JournalPath: See description above: Path of electronic journal files or empty to force usage of DirectIoEvent objects to pass CAT tickets to the application. Default: empty (to force DirectIOEvent usage).
  • JournalWidth: Length of one ticket line stored in the journal or sent vie DirectIOEvent. Must be a value between 28 and 99 (inclusive). Default: 32.
  • MinClaimTimeout: Minimum timeout in milliseconds used by method Claim to ensure correct working. Must be a positive value. If this value is too small, Claim might throw a JposException even if everything is OK if the specified timeout is less than or equal to MinClaimTimeout. Default: 100.
  • Port: The IPv4 address of the device. Must always be specified and not empty. Notation: address:port, where address is a IPv4 address and port the TCP port of the device.
  • RequestTimeout: Maximum time the service object waits for the reception of a response frame after sending a request to the target, in milliseconds. Default: 1000.

  • Field Details

    • CAT_CMD_DISPLAY

      public static final int CAT_CMD_DISPLAY
      EventNumber of DirectIOEvent for display data. Property Data contains line number (starting from 1), Obj contains String object with the display contents.
      See Also:
      Constant Field Values

    • CAT_CMD_TICKET

      public static final int CAT_CMD_TICKET
      EventNumber of DirectIOEvent for ticket data. Property Data contains the target (merchant, customer or both), Obj contains String object with the ticket. The ticket contains no control characters except LF (0Ah, line feed).
      See Also:
      Constant Field Values

    • CAT_DATA_CUSTOMER

      public static final int CAT_DATA_CUSTOMER
      Data value of DirectIOEvent with EventNumber CAT_CMD_TICKET for customer tickets. Such a ticket should be printed and handed over to the customer.
      See Also:
      Constant Field Values

    • CAT_DATA_BOTH

      public static final int CAT_DATA_BOTH
      Data value of DirectIOEvent with EventNumber CAT_CMD_TICKET for merchant and customer tickets. Such a ticket should be printed twice, one to be handed over to the customer and one to be kept by the merchant, in most cases with customer signature.
      See Also:
      Constant Field Values

  • Constructor Details

    • Device

      protected Device​(String id, Object displayName, Object journalPath)
      Constructor. ID is the network address of the credit authorisation terminal (CAT). displayName specifies how display information of the CAT will be performed. journalPath specifies how ticket data provided by the CAT will be handled.
      Parameters:
      id - Network address of the display controller.
      displayName - Value of Jpos.xml property DisplayName (default: null).
      journalPath - Value of Jpos.xml property JournalPath (default: null).

  • Method Details

    • checkProperties

      public void checkProperties​(jpos.config.JposEntry entry) throws jpos.JposException
      Description copied from class: JposBaseDevice
      Checks whether a JposEntry belongs to a predefined property value an if so, sets the corresponding driver value
      Overrides:
      checkProperties in class JposBaseDevice
      Parameters:
      entry - Entry to be checked, contains value to be set
      Throws:
      jpos.JposException - if a property value is invalid

    • changeDefaults

      public void changeDefaults​(CATProperties props)
      Description copied from class: JposDevice
      Change defaults of properties. Must be implemented within derived classed that support credit authorization terminal services.
      Overrides:
      changeDefaults in class JposDevice
      Parameters:
      props - Property set for setting the property defaults

    • changeDefaults

      public void changeDefaults​(ElectronicJournalProperties props)
      Description copied from class: JposDevice
      Change defaults of properties. Must be implemented within derived classed that support electronic journal services.
      Overrides:
      changeDefaults in class JposDevice
      Parameters:
      props - Property set for setting the property defaults

    • removePropertySet

      public boolean removePropertySet​(JposCommonProperties props) throws jpos.JposException
      Description copied from class: JposBaseDevice
      This method removes the given property set from the corresponding property set list and removes the device from the list of all devices, if no further property set is present in any other property set list.
      Overrides:
      removePropertySet in class JposBaseDevice
      Parameters:
      props - Property set to be removed from the corresponding property set list.
      Returns:
      true if the device has been removed from the list of all devices, otherwise false
      Throws:
      jpos.JposException - Source is JposDeviceFactory.deleteDevice. Fails if device cannot be found in list of all devices.

    • sendRecv

      public Object sendRecv​(String command, char resptype, int timeout)
      Method to perform any command, Keep in mind that commands normally generate no response.
      Parameters:
      command - Command data to be sent, without final ETX.
      resptype - Header byte of expected response. If no response is expected: 0.
      timeout - Timeout for whole operation.
      Returns:
      JposException in case of communication error, String containing the response otherwise.

    • sendAbort

      public Object sendAbort()
      Method to send an abort command without waiting for the response.
      Returns:
      JposException in error case, null if no error occurred.

    • run

      public void run()
      Specified by:
      run in interface Runnable

    • getCATProperties

      public CATProperties getCATProperties​(int index)
      Description copied from class: JposDevice
      Returns device implementation of CATProperties.
      Overrides:
      getCATProperties in class JposDevice
      Parameters:
      index - Device index, see constructor of JposCommonProperties.
      Returns:
      Instance of CATProperties that matches the requirements of the corresponding device service.

    • getElectronicJournalProperties

      public ElectronicJournalProperties getElectronicJournalProperties​(int index)
      Description copied from class: JposDevice
      Returns device implementation of ElectronicJournalProperties.
      Overrides:
      getElectronicJournalProperties in class JposDevice
      Parameters:
      index - Device index, see constructor of JposCommonProperties.
      Returns:
      Instance of ElectronicJournalProperties that matches the requirements of the corresponding device service.