client_for_poslynx 0.9.0 → 1.0.0.pre

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OGRhYTY1N2JmMWVkZmVlNzA3MzM3MTBmYjY5YzVhMTE2YTE5YjQ5Mg==
+    N2JjMGU1MmVkOGYwMWJhMzE2NmVmMzRlYjhjNWM4YTE4OTJiN2ZkMA==
   data.tar.gz: !binary |-
-    N2YxY2IzMTUzODE1NjI2OGEwOWE3ZTFiYzVhMTMzY2IzOGExZTRhNQ==
+    YTJhNWNkYzRhYjM5NTJiZGZjYzFmODI1YmU2ODQxNmRmYTI2NTdlMA==
 SHA512:
   metadata.gz: !binary |-
-    MGRlY2MwMTgxMWU3YWExNGIxODE4MDI3NThkZDZjMTkwMmVjM2Y2MDk1MjQ4
-    MTRmODhhYjcxN2VmY2FkOWMwYTU5MjI4MTZmYTY4YTE1MzI3MzIzZDRkNmNm
-    MDRmMGE5ZTZjZDM0YTQ0NzFiNmY0N2ZmMTFiZWFiMTY1MmYxOGI=
+    MDNlOWZjMzQ2ZmUzZDhjM2EwMGM4ZDUxN2JjYjNiZTljOGZiYzRhZGVjMGI1
+    YzgyOTY0NjJhZjYzMTJjYjdmNzY3OTlmMDU0MGI3NTE4ODRmOTQ1NDgxZTcw
+    ZDk0MDhhODlhM2NiYmY4MGMyNWM3MThjM2YzMTYwODc5NGZhYzY=
   data.tar.gz: !binary |-
-    ZjVkODM0YThiMzZlZDFkM2QwZDhlMDY5MDAwMTk1YTUyYzEzNDIxMzQ1YzIw
-    YWNhOWNkZWRiZWM0YjY2MGE3NzY2NmNhOWM1MzRjYTc5MTM1ZmFiMGJkZDVl
-    MTYyMGU1OTliMWM2MDRlMGZhZDEzZjNiYzBhNDQ1NzhiZTU0NjI=
+    NDkxMGJiYzk1ZTBjYzliZGE1YWJjMjFlODUwOWUzMmViNWUyMWM0NTZhZjMz
+    ZDM2OWEzMzFkM2Y5MGJhMjc1ZjAyZjk4ZGE3MjE0YWM2M2RlYzUyOWJkMmRl
+    OGY5ZjQyNzU0NDk2Y2Q2ODk1Y2I1NDAyZDczZjRhZTY4MjMzMDU=

data/README.md

@@ -9,157 +9,181 @@ Technologies.
 Features:
 
 * Data models for requests and responses.
-* Network interaction using an EventMachine protocol.
-* Simplified network interaction using a structured client
-  adapter.
+* Signature image translation to SVG.
+* Network interaction using via EventMachine.
 * A fake POSLynx appliance + PIN Pad script.
 
 ## Overview
 
-The `client_for_poslynx` gem provides network adapters that can
-be used to send requests to a POSLynx unit and receive the
-responses to those requests.  The gem also includes data models
-with XML serialization/deserialization that are used by those
-network adapters or may be used as part of a different network
-adapter if you prefer to build your own.
-
-The first network adapter provided is in the form of a protocol
-for EventMachine. EventMachine is a gem for implementing
-event-driven communication clients and servers.  Essentially,
-being event-driven means that requests are sent and responses are
-received asynchronously.  The application receives a call-back
-when the server responds or the connection is lost, etc.
-
-The second network adapter this gem provides is a "structured"
-(as opposed to event-driven) API.  This is primarily provided
-as a convenience for use in situations where the event-driven
-API is inconvenient, such as when experimenting with the gem
-from an irb command line session.
-
-In addition to the network client libraries, this gem includes
-a script that acts as a fake POSLynx + PIN Pad.  This is useful
-when you are working without access to an actual POSLynx and
-PIN Pad, and want to test your client code and try out
-workflows.  This script will probably be extracted into a
-separate gem soon.
+The `client_for_poslynx` gem provides layers of network adapters
+(operating via EventMachine) that can be used to send requests to
+a POSLynx unit and receive the responses to those requests.  The
+gem also includes data models with XML
+serialization/deserialization that are used by those network
+adapters or may be used as part of another network adapter if you
+prefer to write one of your own.
+
+### Asynchronous Messaging
+
+Message interaction with POSLynx is primarily synchronous, in
+that the client application makes a request, and then waits for
+for a response.  In any realistic integrated POS solution,
+however, there are cases in which it is necessary to devaite from
+the typical synchronous flow.
+
+Let's say that a customer starts an interaction with the
+terminal, gets an emergency call, and runs off without completing
+the interaction. The client application cannot do anything to
+cancel the interaction because it's still blocked waiting for a
+response.
+
+### EventMachine
+
+[EventMachine](http://rubyeventmachine.com/) is a Ruby library
+that supports asynchronous network I/O using event callbacks.
+`client_for_poslynx` provides an EventMachine protocol to allow
+sending requests and receiving responses over an EventMachine
+connection as well as adapter layers to simplify event-based
+interaction via the EventMachine protocol.
+
+One caveat to basing the library around EventMachine is that it
+forces developers to deal with the EventMachine workflow in their
+applications.
+
+### Data Models
+
+The `client_for_poslynx` gem includes data model classes for
+kinds of requests that can be made to the POSLynx as well as for
+responses that can be received from the POSLynx in response to
+requests.
+
+Models can be converted to/from XML-format messages to be sent or
+receive over a network connection to the POSLynx.
+
+These models can be used with the EventManager-based
+communication adapters that exist within the gem, or you can use
+them independently (e.g. if you perfer to communicate with the
+POSLynx using Ruby's standard TCP/IP networking facilities.
+
+Additionally, a `SignatureImage` model is provided that can be
+used to parse or build POSLynx-compatible signature data strings,
+along with a facility for converting signature images to SVG for
+printing or display.
+
+### Fake POS Terminal
+
+The `client_for_poslynx` gem includes a script that acts as a
+fake POSLynx + PIN Pad.  This is useful when you are working
+without access to an actual POSLynx and PIN Pad, and want to test
+your client code and try out workflows.
 
 ## Usage
 
-### Using the structured client
-
-A quick and easy way to try out this gem is to use the structured
-client and example-request factory from an irb console.
-
-Assuming you have a POSLynx host running at 192.168.1.99 on port
-1234 with SSL required, and if your lane has a registered client
-MAC value of 123456789ABC, then with the client_for_poslynx gem
-installed, you should be able to execute a sequence similar to
-the following.
-
-    $ irb
-    1.9.3-p545 :001 > require 'client_for_poslynx'
-     => true
-    1.9.3-p545 :002 > client = ClientForPoslynx::Net::StructuredClient.new('192.168.1.99', 1234, true)
-     => #<ClientForPoslynx::Net::StructuredClient:0x007fefa2103aa8 @directive_queue=#<Queue:0x007fefa21039e0 @que=[], @waiting=[], @mutex=#<Mutex:0x007fefa2103968>>, @activity_queue=#<Queue:0x007fefa2103940 @que=[], @waiting=[], @mutex=#<Mutex:0x007fefa2103300>>, @em_thread=#<Thread:0x007fefa2103260 sleep>>
-    1.9.3-p545 :003 > reqf = ClientForPoslynx::ExampleRequestFactory.new('1234567890ABC')
-     => #<ClientForPoslynx::ExampleRequestFactory:0x007fefa2036030 @client_mac="1234567890ABC">
-    1.9.3-p545 :004 > req = reqf.pin_pad_initialize_request
-     => #<ClientForPoslynx::Data::Requests::PinPadInitialize:0x007fefa204f760 @client_mac="1234567890ABC", @idle_prompt="Example idle prompt">
-    1.9.3-p545 :005 > client.send_request req
-     => nil
-    1.9.3-p545 :006 > client.get_response
-     => #<ClientForPoslynx::Data::Responses::PinPadInitialize:0x007fefa21106e0 @result="Success", @result_text="PinPad Initialized", @error_code="1000", @source_data="<?xml version=\"1.0\" standalone=\"yes\" ?><PLResponse><Command>PPINIT</Command><Result>Success</Result><ResultText>PinPad Initialized</ResultText><ErrorCode>1000</ErrorCode></PLResponse>">
-    1.9.3-p545 :007 > client.end_session
-     => nil
-
-### Using the EventMachine protocol
-
-The following example code demonstrates how to write an
-event-driven client using EventMachine and the POSLynx protocol
-for EventMachine.
-
-    require 'client_for_poslynx'
-    
-    HOST       = '192.168.1.25'
-    PORT       =  12345
-    CLIENT_MAC = '000000000000'
-    USE_SSL    =  true
-    
-    class ButtonSelectionDemo < EM::Connection
-      include EM::Protocols::POSLynx
-    
-      def connection_completed
-        puts "IP connection has been opened"
-        if USE_SSL
-          puts "Starting SSL"
-          start_tls verify_peer: false
-        else
-          puts "Using raw connection. No SSL"
-          display_the_message
-        end
-      end
-    
-      def ssl_handshake_completed
-        puts "SSL session has been successfully started"
-        display_the_message
-      end
-    
-      def display_the_message
-        puts "Sending the PIN Pad Display Message request"
-
-        req = ClientForPoslynx::Data::Requests::PinPadDisplayMessage.new
-        req.client_mac = CLIENT_MAC
-        req.line_count = 2
-        req.text_lines = [
-          "Heads, we clean the basement",
-          "Tails, we go to the movies"
-        ]
-        req.button_labels = %w[ Heads Tails ]
-    
-        send_request req
-      end
-    
-      def receive_response(response)
-        puts "Received response from POSLynx"
-        puts "Result text:     #{response.result_text}"
-        puts "Selected button: #{response.button_response}"
-    
-        puts "Closing the connection"
-        close_connection
-      end
-    
-      def unbind
-        puts "The connection has been closed"
-        puts "Terminating the event loop"
-        EM.stop_event_loop
-      end
-    
-    end
-    
-    # This code will block until the event loop exits.
-    EM.run do
-      EM.connect HOST, PORT, ButtonSelectionDemo
-      EM.error_handler do |e|
-        raise e
-      end
-    end
-    
-    puts "The event loop has ended"
-    puts "Bye"
-    
-    # == Sample output ==
-    # IP connection has been opened
-    # Starting SSL
-    # SSL session has been successfully started
-    # Sending the PIN Pad Display Message request
-    # Received response from POSLynx
-    # Result text:     Success
-    # Selected button: Tails
-    # Closing the connection
-    # The connection has been closed
-    # Terminating the event loop
-    # The event loop has ended
-    # Bye
+### Using the "Request" and "Response" Data Models
+See
+* [`abstract_data.rb`](lib/client_for_poslynx/data/abstract_data.rb)
+* [`requests`](lib/client_for_poslynx/data/requests/)
+* [`responses`](lib/client_for_poslynx/data/responses/)
+
+### Using the `EM_Session` Adapter
+
+[`EM_Session`](lib/client_for_poslynx/net/em_session.rb) is the
+highest level adapter, and the one that you will most likely want
+to use.  It hides the significant complexity of the lower-level
+event-driven interaction behind a synchronous API.  Interruptions
+to the flow are accommodated by allowing multiple sessions to be
+active at the same time and for one to interrupt the other.  This
+"magic" is accomplished through the use of Ruby fibers.
+
+Code examples:
+* [`em_session_basic_example.rb`](examples/em_session_basic_example.rb)
+* [`em_session_interrupt_example.rb`](examples/em_session_interrupt_example.rb)
+
+It is important to note that a session's code block runs on
+EventMachine's event handling thread, and one of the core
+principles of EventMachine is to **never block that thread**.  If
+you need to perform any time-consuming or potentially blocking
+operations in a session, you should run it in a
+`Session#exec_dissociated` block (runs via `EventMachine.defer`).
+If you need to pause for a specific amount of time, then you can
+call the non-blocking `Session#sleep` (runs via
+`EventMachine.add_timer`).
+
+When one session is in progress, and a new session makes a
+request, the new request will attempt to override any pending
+request of the first session, and to "detach" the other session
+so that any of its subsequent request attemtps will be rejected
+and fail with an exception.
+
+In order to avoid race conditions and to ensure that every
+response that is received is returned to the session that made
+the corresponding request, the following rules apply.
+
+1. If one session has a pending request, a new session makes a
+   different kind of request, and then a response to the
+   **second** request is received, then the first session
+   receives an exception, and the second session will have the
+   response reurned.
+2. If one session has a pending request, a new session makes a
+   different kind of request, and then a response to the
+   **first** request is received, then the first session will
+   have that response returned and will be detached.  The second
+   session continues waiting for the subsequent response (to its
+   request).
+2. If one session has a pending `PinPadReset` (`PPRESET`)
+   request, and a new session makes a `PinPadReset` request, then
+   the first session receives an exception, and the response is
+   returned to the second session.
+4. If one session makes a request other than a `PinPadReset`,
+   and a new session makes a request of the same type, then the
+   new session's request fails immediately with an exception.
+
+An important consequence of the rules above is that if the first
+request made by a new session is a `PinPadReset`, then it will
+always be able to successfully interrupt any existing session.
+If it starts with any other kind of request, however, then it has
+the potential to fail as described in rule #4.
+
+For that reason, you should generally start any session with a
+Pin Pad Reset request, and only do otherwise if you have
+considered the consequences with respect to the rules above.
+
+### Using the `EM_Connector` adapter
+
+[`EM_Connector`](lib/client_for_poslynx/net/em_connector.rb) is
+a low-level abstraction around an `EventMachine` connection with
+the [`POSLynx`](lib/client_for_poslynx/net/em_protocol.rb)
+protocol module included.
+
+The jobs of `EM_Connector` are...
+
+1. Simplify the task of making sure that a connection is open and
+   making a request via that connection.
+2. Assist in keeping track of the state of pending requests.
+3. Provide a simple API for specifying callbacks to specific
+   attempts to connection or send a request.
+
+### The `POSLynx` protocol for EventManager
+
+[`POSLynx`](lib/client_for_poslynx/net/em_protocol.rb) is an
+`EventMachine` protocol for sending and receiving POSLynx
+requests and responses.
+
+This protocol is utilized in the same manner as other typical
+`EventManager` protocols, by defining a connection handler class
+that inherits from `EM::Connection` and includes the
+`EM::Protocols::POSLynx` module, and then passing that class as
+the handler argument to `EventMachine.connect`.
+
+Code in the handler can call `#send_request` to send a request
+(an instance of a subclass of
+`ClientForPoslynx::Data::Requests::AbstractRequest`) and can
+override the `#receive_response` method to receive responses
+(instances of subclasses of
+`ClientForPoslynx::Data::Response::AbstractResponse`)
+
+Code example:
+* [`em_protocol_example.rb`](examples/em_protocol_example.rb)
 
 ### Using the `fake_pos_terminal` script
 
@@ -180,8 +204,9 @@ To stop the script, send an interrupt signal by pressing Ctrl+C.
 
 ## Known Limitations
 
-* Only a subset of the possible messages and elements is supported.
-  __More will be added. Contributions are welcome and encouraged. :)__
+* Only a subset of the possible messages and elements is
+  supported.  __More might be added. Contributions are welcome
+  and encouraged. :)__
 
 ## Installation
 
@@ -199,7 +224,7 @@ Or install it yourself as:
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/client_for_poslynx/fork )
+1. Fork it ( `https://github.com/[my-github-username]/client_for_poslynx/fork` )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/examples/em_protocol_example.rb

@@ -0,0 +1,82 @@
+require 'client_for_poslynx'
+
+SERVER_IP   = '192.168.1.25'
+SERVER_PORT =  12345
+CLIENT_MAC  = '000000000000'
+USE_SSL     =  true
+
+class ButtonSelectionDemo < EM::Connection
+  include EM::Protocols::POSLynx
+
+  def connection_completed
+    puts "IP connection has been opened"
+    if USE_SSL
+      puts "Starting SSL"
+      start_tls verify_peer: false
+    else
+      puts "Using raw connection. No SSL"
+      display_the_message
+    end
+  end
+
+  def ssl_handshake_completed
+    puts "SSL session has been successfully started"
+    display_the_message
+  end
+
+  def display_the_message
+    puts "Sending the PIN Pad Display Message request"
+
+    req = ClientForPoslynx::Data::Requests::PinPadDisplayMessage.new
+    req.client_mac = CLIENT_MAC
+    req.line_count = 2
+    req.text_lines = [
+      "Heads, we clean the basement",
+      "Tails, we go to the movies"
+    ]
+    req.button_labels = %w[ Heads Tails ]
+
+    send_request req
+  end
+
+  def receive_response(response)
+    puts "Received response from POSLynx"
+    puts "Result text:     #{response.result_text}"
+    puts "Selected button: #{response.button_response}"
+
+    puts "Closing the connection"
+    close_connection
+  end
+
+  def unbind
+    puts "The connection has been closed"
+    puts "Terminating the event loop"
+    EM.stop_event_loop
+  end
+
+end
+
+# This code will block until the event loop exits.
+EM.run do
+  EM.connect SERVER_IP, SERVER_PORT, ButtonSelectionDemo
+  EM.error_handler do |e|
+    raise e
+  end
+end
+
+puts "The event loop has ended"
+puts "Bye"
+
+# == Sample output ==
+# IP connection has been opened
+# Starting SSL
+# SSL session has been successfully started
+# Sending the PIN Pad Display Message request
+# Received response from POSLynx
+# Result text:     Success
+# Selected button: Tails
+# Closing the connection
+# The connection has been closed
+# Terminating the event loop
+# The event loop has ended
+# Bye