Package de.gmxhome.conrad.jpos.jpos_base

Class JposBase

java.lang.Object
de.gmxhome.conrad.jpos.jpos_base.JposBase
All Implemented Interfaces:
jpos.services.BaseService
Direct Known Subclasses:
BeltService, BillAcceptorService, BillDispenserService, BiometricsService, BumpBarService, CashChangerService, CashDrawerService, CATService, CheckScannerService, CoinAcceptorService, CoinDispenserService, DeviceMonitorService, ElectronicJournalService, ElectronicValueRWService, FiscalPrinterService, GateService, GestureControlService, GraphicDisplayService, HardTotalsService, ImageScannerService, IndividualRecognitionService, ItemDispenserService, KeylockService, LightsService, LineDisplayService, MICRService, MotionSensorService, MSRService, PINPadService, PointCardRWService, POSKeyboardService, POSPowerService, POSPrinterService, RemoteOrderDisplayService, RFIDScannerService, ScaleService, ScannerService, SignatureCaptureService, SmartCardRWService, SoundPlayerService, SoundRecorderService, SpeechSynthesisService, ToneIndicatorService, VideoCaptureService, VoiceRecognitionService
public class JposBase extends Object implements jpos.services.BaseService
Base class for all UPOS device services using this framework. Each service owns a driver object derived from JposDevice and a device class specific property set derived from JposCommonProperties.

Whenever accessing a property or method, the service performs all plausibility checks that are possible without detailed knowledge about a specific physical device. Whenever all parameters are plausible and a method or setter call is generally allowed, a corresponding method of a class that implements the device specific interface be called. This is almost always the correspondong property property set class which implements the corresponding default methods.

These methods have the same name as the method or property name originally called.
Interface methods corresponding to JavaPOS properties have one parameter - the new property value.
Interface methods corresponding to JavaPOS methods that are always be called synchronously have the same parameters as the original method.
For JavaPOS methods that can be called asynchronously, two property set methods are available:

  • A validation method that has the same parameters as the original method. This method must return an object of a method specific class derived from JposOutputRequest with the method's name.
  • An executor method that has one parameter - the object returned by the corresponding validation method.

  • Field Details

    • Props

      public JposCommonProperties Props
      Property set that forms the device service together with class JposDevice and the JposBaseInterface, normally implemented within the property set.

    • Device

      public JposDevice Device
      Device object that holds the service implementation. Only used to access device object directly instead of indirectly via the stored property set.

    • DeviceInterface

      public JposBaseInterface DeviceInterface
      Instance of a class implementing the JposBaseInterface for common getter and method calls bound to the property set. Almost always the same object as Props.

  • Constructor Details

    • JposBase

      public JposBase​(JposCommonProperties props, JposDevice device)
      Constructor. Stores given property set and device implementation object.
      Parameters:
      props - Property set.
      device - Device implementation object.

  • Method Details

    • deleteInstance

      public void deleteInstance() throws jpos.JposException
      Deletes the service instance. Called to perform cleanup operations.
      Throws:
      jpos.JposException - If close() failed or if device cannot be found in list of all devices.

    • logGet

      public void logGet​(String propertyName)
      Generates logging message for the named property.
      Parameters:
      propertyName - Name of the property.

    • logGet

      public void logGet​(Object obj, String propertyName)
      Generates logging message for the named property of the given object.
      Parameters:
      obj - Object that holds the requested property.
      propertyName - Name of the property.

    • getPropertyString

      public String getPropertyString​(Object obj, String propertyName) throws Exception
      Returns a property value of an object as String, using its getter method. Usually, simply the toString method of the specified object will be used to retrieve its string representation. If the property is an array, the string representations of all elements stored within the array will be concatenated separated by comma. Keep in mind that this might be confusing if the string representation of an element itself contains a comma, and that at least MaxArrayStringElements will be retrieved. If an array has more than MaxArrayStringElements elements, further elements will be represented by "...".
      Parameters:
      obj - Object that contains the requested property.
      propertyName - Name of the requested property.
      Returns:
      String representation of the property.
      Throws:
      Exception - Getter not available.

    • removeOuterArraySpecifier

      public String removeOuterArraySpecifier​(Object object, int maxlen)
      Removes outer array specifiers '{' and '}' from string representation of an object created via deepToString. This means, if a String returned by deepToString starts with '{' end ends with '}', both, the first and the last character will be removed from the string.
      Parameters:
      object - The object for which the String representation shall be returned.
      maxlen - Maximum array length, if object or a component of object is an array.
      Returns:
      String representation of object, in case of an array without the starting and final '{' and '}'.

    • deepToString

      public String deepToString​(Object value, int maxlen)
      Converts object to String. Uses method toString to convert the object to a String, but in case of Array objects, a comma separated list of the toString results of the first maxlen elements of the array will be returned instead.
      Parameters:
      value - The object to be converted to a string.
      maxlen - Maximum number of array elements converted to String. If an array consists of more than maxlen elements, the remaining elements will be represented by "...".
      Returns:
      The String representation of value.

    • logPreSet

      public void logPreSet​(String propertyName)
      Generates logging message before setting named property.
      Parameters:
      propertyName - Name of property to be set.

    • logSet

      public void logSet​(String propertyName)
      Generates logging message after named property has been set
      Parameters:
      propertyName - Name of property to be set.

    • logPreCall

      public void logPreCall​(String method, String args)
      Generates logging message before named method will be called.
      Parameters:
      method - Method name.
      args - String specifying the parameters passed to the method.

    • logPreCall

      public void logPreCall​(String method)
      Generates logging message before named method will be called. Version that suppresses parameter dump.
      Parameters:
      method - Method name.

    • logCall

      public void logCall​(String method, String args)
      Generate logging message after successful method call.
      Parameters:
      method - Method name.
      args - empty string or comma separated list of arguments.

    • logCall

      public void logCall​(String method)
      Generate logging message after successful method call. Version without return parameter list.
      Parameters:
      method - Method name.

    • logAsyncCall

      public void logAsyncCall​(String method)
      Generate logging message after successful enqueueing an asynchronous method call.
      Parameters:
      method - Method name.

    • callNowOrLater

      public boolean callNowOrLater​(JposOutputRequest request) throws jpos.JposException
      Call method bound to a specific output request synchronously or asynchronously, depending on AsyncMode property.
      Parameters:
      request - JposOutputRequest to be enqueued
      Returns:
      true if corresponding method will be called asynchronously, false in case of synchronous operation.
      Throws:
      jpos.JposException - If an error occurs during synchronous operation.

    • getAutoDisable

      public boolean getAutoDisable() throws jpos.JposException
      Get common property AutoDisable, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property AutoDisable

    • setAutoDisable

      public void setAutoDisable​(boolean b) throws jpos.JposException
      Set common property AutoDisable, see UPOS specification
      Parameters:
      b - New property value
      Throws:
      jpos.JposException - See UPOS specification, property AutoDisable

    • getDataCount

      public int getDataCount() throws jpos.JposException
      Get common property DataCount, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property DataCount

    • getDataEventEnabled

      public boolean getDataEventEnabled() throws jpos.JposException
      Get common property DataEventEnabled, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property DataEventEnabled

    • setDataEventEnabled

      public void setDataEventEnabled​(boolean b) throws jpos.JposException
      Set common property DataEventEnabled, see UPOS specification
      Parameters:
      b - New property value
      Throws:
      jpos.JposException - See UPOS specification, property DataEventEnabled

    • getCapCompareFirmwareVersion

      public boolean getCapCompareFirmwareVersion() throws jpos.JposException
      Get common property CapCompareFirmwareVersion, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property CapCompareFirmwareVersion

    • getCapUpdateFirmware

      public boolean getCapUpdateFirmware() throws jpos.JposException
      Get common property CapUpdateFirmware, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property CapUpdateFirmware

    • getCapStatisticsReporting

      public boolean getCapStatisticsReporting() throws jpos.JposException
      Get common property CapStatisticsReporting, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property CapStatisticsReporting

    • getCapUpdateStatistics

      public boolean getCapUpdateStatistics() throws jpos.JposException
      Get common property CapUpdateStatistics, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property CapUpdateStatistics

    • getCapPowerReporting

      public int getCapPowerReporting() throws jpos.JposException
      Get common property CapPowerReporting, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property CapPowerReporting

    • getPowerNotify

      public int getPowerNotify() throws jpos.JposException
      Get common property PowerNotify, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property PowerNotify

    • setPowerNotify

      public void setPowerNotify​(int powerNotify) throws jpos.JposException
      Set common property PowerNotify, see UPOS specification
      Parameters:
      powerNotify - New property value
      Throws:
      jpos.JposException - See UPOS specification, property PowerNotify

    • getPowerState

      public int getPowerState() throws jpos.JposException
      Get common property CapCompareFirmwareVersion, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property

    • getAsyncMode

      public boolean getAsyncMode() throws jpos.JposException
      Get common property AsyncMode, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property

    • setAsyncMode

      public void setAsyncMode​(boolean b) throws jpos.JposException
      Get common property AsyncMode, see UPOS specification
      Parameters:
      b - New property value
      Throws:
      jpos.JposException - See UPOS specification, property PowerNotify

    • checkEnabled

      public void checkEnabled() throws jpos.JposException
      Checks whether the device is enabled. If not, throws a JposException with an error code and message that describe the state of the device.
      Throws:
      jpos.JposException - Will be thrown whenever the device is not enabled.

    • checkBusy

      public void checkBusy() throws jpos.JposException
      Checks whether the device is enabled and not busy. If not, throws a JposException with an error code and message that describe the state of the device.
      Throws:
      jpos.JposException - Will be thrown whenever the device is not enabled or busy.

    • checkEnabledUnclaimed

      public void checkEnabledUnclaimed() throws jpos.JposException
      Checks whether the device is enabled and not claimed by another instance. If not, throws a JposException with an error code and message that describe the state of the device.
      Throws:
      jpos.JposException - Will be thrown whenever the device is not enabled.

    • checkFirstEnabled

      public void checkFirstEnabled() throws jpos.JposException
      Checks whether the device has just been enabled once. If not, throws a JposException with an error code and message that describe the state of the device.
      Throws:
      jpos.JposException - Will be thrown whenever the device has never been enabled.

    • checkClaimed

      public void checkClaimed() throws jpos.JposException
      Checks whether the device has been claimed. If not, a JposException will be thrown with the corresponding error code.
      Throws:
      jpos.JposException - Will be thrown whenever the device has not been claimed.

    • checkOpened

      public void checkOpened() throws jpos.JposException
      Checks whether the device has been opened. If not, a JposException will be thrown with the corresponding error code.
      Throws:
      jpos.JposException - Will be thrown whenever the device has not been opened or has been closed.

    • checkNoChangedOrClaimed

      public void checkNoChangedOrClaimed​(Object oldval, Object newval) throws jpos.JposException
      Checks within property set methods whether old and new values are equal or the device has been claimed. If the device is an exclusive-use device and AllowAlwaysSetProperties has been set to false via jpos.xml, a JposException will be thrown.
      Parameters:
      oldval - Property value to be changed.
      newval - New property value.
      Throws:
      jpos.JposException - Will be thrown whenever the throwing condition is met.

    • check

      public static void check​(boolean condition, int err, String errtxt) throws jpos.JposException
      To allow calling JposDevice method check without JposDevice. prefix, we pass all parameters to JposDevice.check unchanged.
      Parameters:
      condition - Same condition as in JposDevice.
      err - Same error code as in JposDevice.
      errtxt - Same text as in JposDevice.
      Throws:
      jpos.JposException - If condition is true.

    • check

      public void check​(boolean condition, int units, int error, int ext, String message) throws jpos.JposException
      Check method for device classes that support a subsystem of up to 32 units. Checks condition and if true, sets error properties and throws JposException. This method may only be used if it is absolutely clear that the check is made within a synchronous UPOS method. If this is not the case, use method checkwith additional parameter synchrone. This is almost always the case in methods that have one parameter derived from JposOutputRequest. You can check whether property EndSync of the request equals null (asynchronous call) or not (synchronous call).
      Parameters:
      condition - Error condition.
      units - Units to be filled in ErrorUnits.
      error - Error code.
      ext - Extended error code.
      message - Error message, same message for ErrorString and JposException.
      Throws:
      jpos.JposException - If Error condition is true.

    • check

      public void check​(boolean condition, int units, int error, int ext, String message, boolean synchrone) throws jpos.JposException
      Check method for device classes that support a subsystem of up to 32 units. Checks condition and if true, sets error properties and throws JposException.
      Parameters:
      condition - Error condition.
      units - Units to be filled in ErrorUnits.
      error - Error code.
      ext - Extended error code.
      message - Error message, same message for ErrorString and JposException.
      synchrone - True if method has been called synchronously, false otherwise.
      Throws:
      jpos.JposException - If Error condition is true.

    • check

      public void check​(Exception cause, int units, int error, int ext, boolean synchrone) throws jpos.JposException
      Check method for device classes that support a subsystem of up to 32 units. Check condition and if true, sets error properties and throws JposException. If the error cause
      Parameters:
      cause - The Exception that caused the error. A value of null can be passed if no error occurred.
      units - Units to be filled in ErrorUnits.
      error - Error code.
      ext - Extended error code.
      synchrone - True if method has been called synchronously, false otherwise.
      Throws:
      jpos.JposException - If Error condition is true.

    • getOutputID

      public int getOutputID() throws jpos.JposException
      Get common property OutputID, see UPOS specification
      Returns:
      property value
      Throws:
      jpos.JposException - See UPOS specification, property

    • compareFirmwareVersion

      public void compareFirmwareVersion​(String firmwareFileName, int[] result) throws jpos.JposException
      Common method compareFirmwareVersion, see UPOS specification
      Parameters:
      firmwareFileName - See UPOS specification, method compareFirmwareVersion
      result - See UPOS specification, method compareFirmwareVersion
      Throws:
      jpos.JposException - See UPOS specification, method compareFirmwareVersion

    • updateFirmware

      public void updateFirmware​(String firmwareFileName) throws jpos.JposException
      Common method updateFirmware, see UPOS specification
      Parameters:
      firmwareFileName - See UPOS specification, method updateFirmware
      Throws:
      jpos.JposException - See UPOS specification, method updateFirmware

    • resetStatistics

      public void resetStatistics​(String statisticsBuffer) throws jpos.JposException
      Common method resetStatistics, see UPOS specification
      Parameters:
      statisticsBuffer - See UPOS specification, method resetStatistics
      Throws:
      jpos.JposException - See UPOS specification, method resetStatistics

    • retrieveStatistics

      public void retrieveStatistics​(String[] statisticsBuffer) throws jpos.JposException
      Common method retrieveStatistics, see UPOS specification
      Parameters:
      statisticsBuffer - See UPOS specification, method retrieveStatistics
      Throws:
      jpos.JposException - See UPOS specification, method retrieveStatistics

    • updateStatistics

      public void updateStatistics​(String statisticsBuffer) throws jpos.JposException
      Common method updateStatistics, see UPOS specification
      Parameters:
      statisticsBuffer - See UPOS specification, method updateStatistics
      Throws:
      jpos.JposException - See UPOS specification, method updateStatistics

    • clearOutput

      public void clearOutput() throws jpos.JposException
      Common method clearOutput, se UPOS specification
      Throws:
      jpos.JposException - See UPOS specification, method clearOutput

    • clearInput

      public void clearInput() throws jpos.JposException
      Common method clearInput, see UPOS specification
      Throws:
      jpos.JposException - see UPOS specification

    • clearInputProperties

      public void clearInputProperties() throws jpos.JposException
      Common method clearInputProperties, see UPOS specification
      Throws:
      jpos.JposException - see UPOS specification

    • getCheckHealthText

      public String getCheckHealthText() throws jpos.JposException
      Specified by:
      getCheckHealthText in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getClaimed

      public boolean getClaimed() throws jpos.JposException
      Specified by:
      getClaimed in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getDeviceEnabled

      public boolean getDeviceEnabled() throws jpos.JposException
      Specified by:
      getDeviceEnabled in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • setDeviceEnabled

      public void setDeviceEnabled​(boolean enable) throws jpos.JposException
      Specified by:
      setDeviceEnabled in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getDeviceServiceDescription

      public String getDeviceServiceDescription() throws jpos.JposException
      Specified by:
      getDeviceServiceDescription in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getDeviceServiceVersion

      public int getDeviceServiceVersion() throws jpos.JposException
      Specified by:
      getDeviceServiceVersion in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getFreezeEvents

      public boolean getFreezeEvents() throws jpos.JposException
      Specified by:
      getFreezeEvents in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • setFreezeEvents

      public void setFreezeEvents​(boolean freezeEvents) throws jpos.JposException
      Specified by:
      setFreezeEvents in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getPhysicalDeviceDescription

      public String getPhysicalDeviceDescription() throws jpos.JposException
      Specified by:
      getPhysicalDeviceDescription in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getPhysicalDeviceName

      public String getPhysicalDeviceName() throws jpos.JposException
      Specified by:
      getPhysicalDeviceName in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • getState

      public int getState() throws jpos.JposException
      Specified by:
      getState in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • claim

      public void claim​(int timeout) throws jpos.JposException
      Specified by:
      claim in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • startClaiming

      public JposCommonProperties startClaiming​(SyncObject waiter)
      Starts claiming. Should be called whenever a device tries to claim a device.
      Returns null, if the device is not claimed. Otherwise, the given SyncObject instance will be inserted into the ClaimWaiters list of the claiming instance. Since this object will be signalled during release or close of that instance, it should be used to wait before retrying start claiming.
      Parameters:
      waiter - SyncOject to be used for synchronization with currently claiming instance, if any.
      Returns:
      null on success, property set of currently claiming instance otherwise.

    • signalRelease

      public void signalRelease()
      Signals release after claim. Should be called whenever a claimed device becomes unclaimed to wake up any other waiting instances.

    • close

      public void close() throws jpos.JposException
      Specified by:
      close in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • checkHealth

      public void checkHealth​(int level) throws jpos.JposException
      Specified by:
      checkHealth in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • directIO

      public void directIO​(int command, int[] data, Object object) throws jpos.JposException
      Specified by:
      directIO in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • open

      public void open​(String logicalName, jpos.services.EventCallbacks eventCallbacks) throws jpos.JposException
      Specified by:
      open in interface jpos.services.BaseService
      Throws:
      jpos.JposException

    • release

      public void release() throws jpos.JposException
      Specified by:
      release in interface jpos.services.BaseService
      Throws:
      jpos.JposException