Package de.gmxhome.conrad.jpos.jpos_base

Class JposBaseDevice

java.lang.Object
de.gmxhome.conrad.jpos.jpos_base.JposBaseDevice
Direct Known Subclasses:
JposDevice
public class JposBaseDevice extends Object
Base class for device driver implementation based on JPOS framework.
Implements event handling, methods for plausibility checks, properties that are common for all device instances, logging methods and some general helper methods.
Device specific properties will be specified in property sets stored in device type specific classes named DeviceTypeProperties or derived classes.

Property getters are implemented directly within the corresponding DeviceTypeService class.
Final parts of setters and methods have been implemented in classes that implement DeviceTypeInterface, an interface derived from interface JposBaseInterface. A Default implementation implementing basic functionality that is always necessary and that can be used for derived classes has been made within the DeviceTypeProperties classes.
Methods that can me performed asynchronously are split into two parts: A validation part returning a method specific object derived from class MethodName (where methodName is the name of the corresponding method) and the real final part with the same method name, but with only the object returned by the corresponding validation part as parameter.
Common properties, methods and setters have been defined within JposCommonProperties which implements JposBaseInterface. An instance of a DeviceTypeInterface as well as the corresponding JposBaseInterface will be stored in each property set in the member variables DeviceInterface and DeviceTypeInterface.
The specific interface methods and setters will be called by the corresponding setter or method implementation of the corresponding DeviceTypeService class after all plausibility checks have been performed. Therefore, only physical device specific checks must be performed within these methods.

Setter implementations have the same names as the corresponding UPOS property. One parameter, the new property value, will be passed.
Method implementations have the same name as the corresponding UPOS method. In case of methods that can only performed synchronously, they have the same parameters as the corresponding UPOS method. Methods that can be performed asynchronously as well are only for validation and return an object derived from the class with the name of the UPOS method on success (such classes are always derived from JposOutputRequest). The real final part must be implemented in a method with the same name but with the object returned by the validation part as only parameter. Keep in mind that the time this method is called is always the time at the processing shall start. This is typically within the output request worker thread.

Here a full list of all properties, common for all device classes, that can be changed via jpos.xml:

  • AllowAlwaysSetProperties: For all exclusive-use devices where UPOS specifies properties with read-write access before the device has been opened, This property specifies whether write access will be suppressed by the service (false) or not (true) until the device has been claimed. The default must be set within the constructor of a device derived from JposDevice.
    However, even if set, the individual service implementation can decide to throw a JposException whenever the application tries to change a writable property until the device has been claimed, but only if not set, the service method checkOpenNotClaimed will throw the JposException without calling the device specific set method.
  • DrawerBeepVolume: For all CashDrawer devices, a beep volume between 0 and 127 can be specified. Default is implementation specific.
  • LoggerName: Name of the logger. See Log4j specification for more details.
  • LoggerFormat: Layout pattern, if not set, SimpleLayout will be used. See Log4j specification for more details.
  • LogFilePath: Path of log file.
  • LogFilePattern: If set, file pattern for DailyRollingFileAppender, otherwise FileAppender will be used. See Log4j specification for more details.
  • LogLevel: One of all, trace, debug, info, warn, error, fatal or off. Specifies the logging level. See Log4pos specification for more details.
  • MaxArrayStringElements: Specifies the maximum number of elements of an object to be logged that are fully logged. If an object to be logged has more elements, the remaining elements will be logged as "...".
  • MaximumConfirmationEventWaitingTime: Specifies the maximum time an event callback may block event handling. Default: FOREVER. KEEP IN MIND: Setting this property to a different value leads to a service that does not fully fulfill the requirements of the UPOS specification: Running more than one event handler callback becomes possible.
  • SerialIOAdapterClass: Name of the SerialIOAdapter class. No default, must be set if serial communication shall be used. The following adapter classes have been implemented:
    • de.gmxhome.conrad.JNAWindows.JnaSerial: Serial IO implementation using WIN32 API via JNA.
    • de.gmxhome.conrad.JNALinux.JnaLinuxSerial: Serial IO implementation using Linux API via JNA.
    • de.gmxhome.conrad.jSerialComm.JSCSerial: Serial IO implementation using jSerialComm framework.
    • de.gmxhome.conrad.jSSC.JSSCSerial: Serial IO implementation using jSSC framework.
  • StrictFIFOEventHandling: If true, all events will be delivered in the same sequence as they have been fired. If false, data end input error events can be bypassed by other events as long as DataEventEnabled and FreezeEvents are false. Default is false.

  • Field Details

    • PhysicalDeviceDescription

      public String PhysicalDeviceDescription
      UPOS property PhysicalDeviceDescription. Default: "Default implementation for any device". For more details, see UPOS specification, chapter Common Properties, Methods and Events.

    • PhysicalDeviceName

      public String PhysicalDeviceName
      UPOS property PhysicalDeviceName. Default: "Any Device". For more details, see UPOS specification, chapter Common Properties, Methods and Events.

    • CapCompareFirmwareVersion

      public boolean CapCompareFirmwareVersion
      UPOS property CapCompareFirmwareVersion. Default: false. For more details, see UPOS specification, chapter Common Properties, Methods and Events.

    • CapUpdateFirmware

      public boolean CapUpdateFirmware
      UPOS property CapUpdateFirmware. Default: false. For more details, see UPOS specification, chapter Common Properties, Methods and Events.

    • CapPowerReporting

      public int CapPowerReporting
      UPOS property CapPowerReporting. Default: PR_NONE. For more details, see UPOS specification, chapter Common Properties, Methods and Events.

    • ID

      protected String ID
      Device identifier, specifies the interface the device is connected. For example, COM port name or IP address, (COM1, 192.168.1.150, ...).

    • Log

      public net.bplaced.conrad.log4jpos.Logger Log
      Logger object.

    • LoggerName

      public String LoggerName
      Logger name.

    • LogFilePath

      public String LogFilePath
      Path of log file.

    • LogFilePattern

      public String LogFilePattern
      File pattern of log file. Example: ".YYYY-MM"

    • LogLevel

      public net.bplaced.conrad.log4jpos.Level LogLevel
      Logging level. Example: Level.DEBUG, see Log4j specification

    • LoggerFormat

      public String LoggerFormat
      Format string for logging line. See Log4j specification

    • MaxArrayStringElements

      public int MaxArrayStringElements
      Maximum number of array elements used for its string representation. Default: 100. Can be changed via jpos.xml.

    • PendingCommands

      public List<JposOutputRequest> PendingCommands
      List holds all outstanding output requests.

    • AsyncProcessorRunning

      public final JposOutputRequest.JposRequestThread[] AsyncProcessorRunning
      Flag that signals whether the processor for asynchronous commands is running. Used for synchronization purposes.

    • CurrentCommand

      public JposOutputRequest CurrentCommand
      Currently executed output request, if concurrent asynchronous requests are not supported.

    • DrawerBeepVolume

      @Deprecated public Integer DrawerBeepVolume
      Deprecated.
      Volume for drawer beep. Valid values are from 0 to 127. Will be initialized with an Integer object only for devices that support at least one CashDrawer device. Deprecated, the corresponding property in a device class specific property set will be set within the device class specific checkProperties method called by the addDevice method of the specific factory class.

    • AllowAlwaysSetProperties

      @Deprecated public boolean AllowAlwaysSetProperties
      Deprecated.
      Temporary storage for jpos.xml property AllowAlwaysSetProperties. Specifies how the service instance shall handle write access to writable properties while the device has not been claimed for exclusive-use devices:
      If true, setting such properties will remain possible and it is up to the service how to handle the new value. Since no physical access to the device is allowed until the device has been claimed, the service can buffer the new value for later use after a successful call of method claim.
      If false, only read access will be possible until the device has been claimed. If the application tries to change a writable property, a JposException will be thrown with error code E_NOTCLAIMED. The default value is true. Method checkProperties will be used to change it to the value specified in jpos.xml, if specified, and method changeDefaults will be used to copy this value to the corresponding property set and to reset it back to its default. Deprecated. Use the corresponding property within the device class specific property set object.

    • JposVersion

      @Deprecated public Integer JposVersion
      Deprecated.
      Holds the JavaPOS control version as specified in jpos.xml. Can be used in changeDefaults method of the corresponding logical device. Default: null (not set). Will be reset to null within method changeDefaults of JposDevice. Every service implementation that likes to use that value must save it within its own changeDefaults method before calling super.changeDefaults.
      Deprecated. Use DeviceServiceVersion instead.

    • SerialIOAdapterClass

      public static String SerialIOAdapterClass
      Name of the SerialIOAdapter class. No default, must be set in device specific implementation if serial communication shall be supported.

    • MaximumConfirmationEventWaitingTime

      @Deprecated public int MaximumConfirmationEventWaitingTime
      Deprecated.
      Maximun number of milliseconds the event handling is delayed after delivery of events that need confirmation. Default is JPOS_FOREVER (unlimited number of seconds). Deprecated: Use MaximumConfirmationEventWaitingTime from property set instead.

    • StrictFIFOEventHandling

      @Deprecated public boolean StrictFIFOEventHandling
      Deprecated.
      Specifies whether event handling strictly confirms the UPOS specification or if data and input error events can be delivered delayed while DataEventEnabled is false. Default is false (data and input error events do not block other events while DataEventEnabled is false). Deprecated: Use StrictFIFOEventHandling from property set instead.

  • Constructor Details

    • JposBaseDevice

      protected JposBaseDevice​(String id)
      Constructor. Initialize ID. Derived classes must allocate list of list of property sets for all supported device types.
      Parameters:
      id - Device ID, typically a unique identifier, like the COM port, e.g. "COM1"

  • Method Details

    • invokeRequestThread

      public void invokeRequestThread​(JposOutputRequest request, Class<?> immediate)
      Invokes a JposRequestThread for handling the specified request. If an immediate class has been specified (not null), it specifies a high priority class. Requests of a high priority class will be inserted before the first request with normal priority (immediate requests). All other requests will be appended at the end of the request queue.
      After insertion, the request handler thread will be created and started if it is currently not running.
      Parameters:
      request - Request to be added. If null, only handler thread invocation, if necessary.
      immediate - If specified, class with high priority.

    • concurrentProcessingSupported

      public Boolean concurrentProcessingSupported​(JposOutputRequest request)
      Method with checks whether the device supports concurrent processing for the given request. This default implementation returns always false. You must override this method in derived classes to allow specific requests to be invoked concurrently.
      Parameters:
      request - Request to be checked.
      Returns:
      true if the request can be processed concurrently. Otherwise, false will be returned if synchronization with other requests of the device is necessary. If only serialization with other non-concurrent requests of the same service is necessary, null can be returned.

    • createConcurrentRequestThread

      public void createConcurrentRequestThread​(JposOutputRequest request)
      Starts a new thread for concurrent asynchronous processing and adds it to the CurrentCommands list of the property set the request belongs to.
      Parameters:
      request - Request to be invoked.

    • getRequestRunnersRequest

      public JposOutputRequest getRequestRunnersRequest​(Runnable runner)
      Retrieves JposOutputRequest belonging to a RequestRunner object or null, if the given Runnable is no RequestRunner
      Parameters:
      runner - Runnable, almost always a RequestRunner.
      Returns:
      runner.Request, if runner is an instance of RequestRunner, otherwise null.

    • getCount

      public static int getCount​(List<JposCommonProperties>[] device)
      Get count of device type specific property sets stored within a device driver.
      Parameters:
      device - List of list to be processed
      Returns:
      No. of non-null property set objects stored within list of list

    • synchronizedMessageBox

      public static void synchronizedMessageBox​(String message, String title, int messageType)
      Show message dialog within swing thread + synchronization. Useful in interactive CheckHealth methods
      Parameters:
      message - see JoptionPane.showMessageBox
      title - see JoptionPane.showMessageBox
      messageType - see JoptionPane.showMessageBox

    • check

      public static void check​(boolean condition, int err, String errtxt) throws jpos.JposException
      Checks whether the given condition it met. If so, throws a JposException with the given error code and error description
      Parameters:
      condition - Error condition
      err - Jpos error code
      errtxt - Corresponding error text
      Throws:
      jpos.JposException - Will be thrown if condition is true

    • checkext

      public static void checkext​(boolean condition, int ext, String errtxt) throws jpos.JposException
      Checks whether the given condition it met. If so, throws a JposException with JPOS_E_EXTENDED and the given extended error code and error description
      Parameters:
      condition - Error condition
      ext - Jpos extended error code
      errtxt - Corresponding error text
      Throws:
      jpos.JposException - Will be thrown if condition is true

    • checkMember

      public static void checkMember​(long value, long[] allowedValues, int err, String errtxt) throws jpos.JposException
      Checks whether the given value is member of the given set of allowed values. Throws JposException if given value does not match any value in allowed value set.
      Parameters:
      value - Value to be checked
      allowedValues - Set of allowed values
      err - JPOS error code
      errtxt - Error text
      Throws:
      jpos.JposException - will be thrown if value does not match any value in allowedValues

    • member

      public static boolean member​(long value, long[] allowedValues)
      Checks whether the given value is member of the given set of allowed values.
      Parameters:
      value - Value to be checked
      allowedValues - Set of allowed values
      Returns:
      true if value is containaed in allowedValues

    • member

      public static boolean member​(String value, String[] allowedValues)
      Checks whether the given value is member of the given set of allowed values.
      Parameters:
      value - Value to be checked
      allowedValues - Set of allowed values
      Returns:
      true if value is containaed in allowedValues

    • stringArrayToLongArray

      public static long[] stringArrayToLongArray​(String[] stringarray)
      Converts string array that contains integer values into long[].
      Parameters:
      stringarray - String array containing long integer values.
      Returns:
      Array of long values containing the values stored in stringarray.

    • checkRange

      public static void checkRange​(long value, long min, long max, int err, String errtxt) throws jpos.JposException
      Checks whether the given value is out of range. Throws JposException if given value is not between minimum and maximum value.
      Parameters:
      value - Value to be checked
      min - Minimum allowed value
      max - Maximum allowed value
      err - JPOS error code
      errtxt - Error text
      Throws:
      jpos.JposException - will be thrown if not min ≤ value ≤ max

    • delay

      public static void delay​(int millis)
      Delay current thread for the given time period.
      Parameters:
      millis - Number of milliseconds the thread shall be delayed.

    • log

      public void log​(Object loglevel, String message)
      Performs logging. Includes automatic logger initialization whenever necessary and possible. However, if logger intialization is not possible due to missing entries in jpos.xml, no logging will be made.
      Parameters:
      loglevel - Logging loglevel, any Level object from log4j, log4jpos or java.util.logging
      message - Message to be logged

    • checkProperties

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

    • handleEvent

      public void handleEvent​(JposDataEvent event) throws jpos.JposException
      Enqueues or fires data event. If FreezeEvent is false, the event will be fired immediately. Otherwise, it will be enqueued and fired after FreezeEvents will be reset. In addition, properties DeviceEnabled, DataEventEnabled and DataCount will be adjusted as described in the UPOS specification
      Parameters:
      event - Event to be fired.
      Throws:
      jpos.JposException - In case of an error during deviceEnable(false) due to AutoDisable = true.

    • handleEvent

      public void handleEvent​(JposErrorEvent event) throws jpos.JposException
      Enqueues or fires error event. If FreezeEvent is false, the event will be fired immediately. Otherwise, it will be enqueued and fired after FreezeEvents will be reset.
      Parameters:
      event - Event to be fired
      Throws:
      jpos.JposException - If error occurs during event handling

    • handleEvent

      public void handleEvent​(JposStatusUpdateEvent event) throws jpos.JposException
      Enqueues or fires status update event. If FreezeEvent is false, the event will be fired immediately. Otherwise, it will be enqueued and fired after FreezeEvents will be reset. In case of sharable devices, the event will be fired to all devices controls that enabled the same physical device.
      Parameters:
      event - Event to be fired
      Throws:
      jpos.JposException - If error occurs during event handling

    • handleEvent

      public void handleEvent​(JposOutputCompleteEvent event) throws jpos.JposException
      Enqueues or fires output complete event. If FreezeEvent is false, the event will be fired immediately. Otherwise, it will be enqueued and fired after FreezeEvents will be reset.
      Parameters:
      event - Event to be fired
      Throws:
      jpos.JposException - If error occurs during event handling

    • handleEvent

      public void handleEvent​(JposTransitionEvent event) throws jpos.JposException
      Enqueues or fires transition event. If FreezeEvent is false, the event will be fired immediately. Otherwise, it will be enqueued and fired after FreezeEvents will be reset.
      Parameters:
      event - Event to be fired
      Throws:
      jpos.JposException - If error occurs during event handling

    • handleEvent

      public void handleEvent​(JposDirectIOEvent event) throws jpos.JposException
      Enqueues or fires direct IO event. If FreezeEvent is false, the event will be fired immediately. Otherwise, it will be enqueued and fired after FreezeEvents will be reset.
      Parameters:
      event - Event to be fired
      Throws:
      jpos.JposException - If error occurs during event handling

    • prepareSignalStatusWaits

      public void prepareSignalStatusWaits​(List<JposCommonProperties> propertylist)
      Prepares device for later signalling status waits via signalStatusWaits method. Ensures that only those waiting instances will be signalled that are still waiting during preparation. In case of situations where status lookup and status changing commands can be invoked in different threads, this method should be called before invoking the status lookup to ensure that an invocation of signalStatusWaits after the lookup will only signal those threads that started waiting before the lookup started.
      Parameters:
      propertylist - list of property sets to be used for SyncObject lookup.

    • signalStatusWaits

      public void signalStatusWaits​(List<JposCommonProperties> propertylist)
      Signals SyncObject objects attached to any property set bound to the device. If prepareSignalStatusWaits has been invoked for the same property set list previously, only those objects will be signalled that have been attached before the last call to prepareSignalStatusWaits. Otherwise, all attached objects will be signalled.
      Parameters:
      propertylist - list of property sets to be used for SyncObject lookup.

    • handlePowerStateOnEnable

      public void handlePowerStateOnEnable​(JposCommonProperties dev) throws jpos.JposException
      Sets PowerState property to its current value and fires status update event, passing this state to the application.
      Parameters:
      dev - Device property set
      Throws:
      jpos.JposException - If an error ocurs during event firing

    • processEventList

      protected void processEventList​(JposCommonProperties dev) throws jpos.JposException
      Process the event queue. Fires all notification events except data events while FreezeEvents = false.
      Parameters:
      dev - Property set to be used for event processing
      Throws:
      jpos.JposException - If EventFirer object cannot be created.

    • postTransitionProcessing

      public void postTransitionProcessing​(JposTransitionEvent trevent)
      Retrieves TransitionEvent after application could modify pData and pString. Allows the device service to continue further processing as requested.
      Parameters:
      trevent - JposTransitionEvent after return from application callback. null if the device control does not support transition events.

    • postDirectIOProcessing

      public void postDirectIOProcessing​(JposDirectIOEvent dioevent)
      Retrieves DirectIOEvent after application could modify data and obj. Allows the device service to continue further processing as requested.
      Parameters:
      dioevent - JposDirectIOEvent after return from application callback.

    • removePropertySet

      public boolean removePropertySet​(JposCommonProperties props) throws jpos.JposException
      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.
      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.

    • noOfPropertySets

      public int noOfPropertySets()
      Method that returns the number of property sets hold by this device. It is the sum of all property sets, created for each open of any device class handled by this device.
      This method is only a dummy, overwritten in class JposDevice.
      Returns:
      Number of property sets bound to this device.

    • getClaimingInstance

      public JposCommonProperties getClaimingInstance​(JposCommonProperties[] claimedDevices, int index)
      Retrieves a claiming device from a device claimer array. Should be used to access the property set of any currently claiming device.
      Parameters:
      claimedDevices - Array of claiming devices. One of ClaimedCashDrawer, ClaimedKeylock, ...
      index - Index of property set within the array. Must be between 0 and the length of claimedDevices.
      Returns:
      Propetry set of claiming device or null if device[index] has not been claimed or if index is out of range.

    • getPropertySetInstance

      public JposCommonProperties getPropertySetInstance​(List<JposCommonProperties>[] propertysets, int deviceindex, int propertysetindex)
      Retrieves a device instance from the list of all instances bound to a specific device.
      Parameters:
      propertysets - List of list of property sets bound to one of the devices of same device type.
      deviceindex - Index of the requested device.
      propertysetindex - Index of the requested property set.
      Returns:
      Requested property set or null if deviceindex or propertysetindex is out of range.