jubilee 0.5.0 → 1.0.0.beta1

data/lib/vertx/buffer.rb

@@ -0,0 +1,251 @@
+# Copyright 2011-2012 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'vertx/shared_data'
+
+module Vertx
+
+  # A Buffer represents a sequence of zero or more bytes that can be written to or read from, and which expands
+  # as necessary to accomodate any bytes written to it.
+  #
+  # Buffers are used in many places in vert.x, for example to read/write data to/from {NetSocket}, {AsyncFile},
+  # {WebSocket}, {HttpClientRequest}, {HttpClientResponse}, {HttpServerRequest}, {HttpServerResponse} etc.
+  #
+  # There are two ways to write data to a Buffer: The first method involves methods that take the form set_XXX.
+  # These methods write data into the buffer starting at the specified position. The position does not have to be inside data that
+  # has already been written to the buffer; the buffer will automatically expand to encompass the position plus any data that needs
+  # to be written. All positions are measured in bytes and start with zero.
+  #
+  # The second method involves methods that take the form append-XXX; these methods append data at the end of the buffer.
+  # Methods exist to both set and append all primitive types, String and  other instances of Buffer.
+  #
+  # Data can be read from a buffer by invoking methods which take the form get_XXX. These methods take a parameter
+  # representing the position in the Buffer from where to read data.
+  #
+  # @author {http://tfox.org Tim Fox}
+  class Buffer
+
+    # @private
+    def initialize(j_buffer)
+      @buffer = j_buffer
+    end
+
+    # Creates a new empty buffer. The {#length} of the buffer immediately after creation will be zero.
+    # @param initial_size_hint [FixNum] is a hint to the system for how much memory
+    # to initially allocate to the buffer to prevent excessive automatic re-allocations as data is written to it.
+    def Buffer.create(initial_size_hint = 0)
+      Buffer.new(org.vertx.java.core.buffer.Buffer.new(initial_size_hint))
+    end
+
+    # Create a new Buffer from a String
+    # @param str [String] The String to encode into the Buffer
+    # @param enc [String] Encoding to use. Defaults to "UTF-8"
+    def Buffer.create_from_str(str, enc = "UTF-8")
+      Buffer.new(org.vertx.java.core.buffer.Buffer.new(str, enc))
+    end
+
+    # Return a String representation of the buffer.
+    # @param enc [String] The encoding to use. Defaults to "UTF-8"
+    # @return [String] a String representation of the buffer.
+    def to_s(enc = "UTF-8")
+      @buffer.toString(enc)
+    end
+
+    # Get the byte at position pos in the buffer.
+    # @param pos [FixNum] the position in the buffer from where to retrieve the byte
+    # @return [FixNum] the byte
+    def get_byte(pos)
+      @buffer.getByte(pos)
+    end
+
+    # Get the FixNum represented by a sequence of bytes starting at position pos in the buffer.
+    # @param pos [FixNum] the position in the buffer from where to retrieve the FixNum.
+    # @param bytes [FixNum] the number of bytes to retrieve from position pos to create the FixNum. Valid values are 1, 2, 4 and 8.
+    # @return [FixNum] the FixNum
+    def get_fixnum(pos, bytes)
+      case bytes
+        when 1
+          @buffer.getByte(pos)
+        when 2
+          @buffer.getShort(pos)
+        when 4
+          @buffer.getInt(pos)
+        when 8
+          @buffer.getLong(pos)
+        else
+          raise "bytes must be 1, 2, 4, or 8"
+      end
+    end
+
+    # Get the Float represented by a sequence of bytes starting at position pos in the buffer.
+    # @param pos [Float] the position in the buffer from where to retrieve the Float.
+    # @param bytes [Float] the number of bytes to retrieve from position pos to create the Float. Valid values are 4 and 8.
+    # @return [Float] the Float
+    def get_float(pos, bytes)
+      case bytes
+        when 4
+          @buffer.getFloat(pos)
+        when 8
+          @buffer.getDouble(pos)
+        else
+          raise "bytes must be 4 or 8"
+      end
+    end
+
+    # Return bytes from the buffer interpreted as a String
+    # @param pos [FixNum] the position in the buffer from where to start reading
+    # @param end_pos [FixNum] the position in the buffer to end reading
+    # @param enc [String] The encoding to use
+    # @return [String] the String
+    def get_string(pos, end_pos, enc = 'UTF-8')
+      @buffer.getString(pos, end_pos, enc)
+    end
+
+    # Return bytes in the buffer as a Buffer
+    # @param start_pos [FixNum] - the position in this buffer from where to start the copy.
+    # @param end_pos [FixNum] - the copy will be made up to index end_pos - 1
+    # @return [Buffer] the copy
+    def get_buffer(pos, end_pos)
+      j_buff = @buffer.getBuffer(pos, end_pos)
+      Buffer.new(j_buff)
+    end
+
+    # Appends another buffer to the end of this buffer. The buffer will expand as necessary to accomodate any bytes
+    # written.
+    # @param buff [Buffer] the buffer to append.
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def append_buffer(buff)
+      @buffer.appendBuffer(buff._to_java_buffer)
+      self
+    end
+
+    # Appends a FixNum to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written.
+    # @param num [FixNum] the fixnum to append.
+    # @param bytes [FixNum] the number of bytes to write in the buffer to represent the fixnum. Valid values are 1, 2, 4 and 8.
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def append_fixnum(num, bytes)
+      case bytes
+        when 1
+          @buffer.appendByte(num)
+        when 2
+          @buffer.appendShort(num)
+        when 4
+          @buffer.appendInt(num)
+        when 8
+          @buffer.appendLong(num)
+        else
+          raise "bytes must be 1, 2, 4, or 8"
+      end
+      self
+    end
+
+    # Appends a Float to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written.
+    # @param num [Float] the float to append.
+    # @param bytes [FixNum] the number of bytes to write in the buffer to represent the float. Valid values are 4 and 8.
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def append_float(num, bytes)
+      case bytes
+        when 4
+          @buffer.appendFloat(num)
+        when 8
+          @buffer.appendDouble(num)
+        else
+          raise "bytes must be 4 or 8"
+      end
+    end
+
+    # Appends a string to the end of this buffer. The buffer will expand as necessary to accomodate any bytes written.
+    # @param str [String] the string to append.
+    # @param enc [String] the encoding to use. Defaults to "UTF-8"
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def append_str(str, enc = "UTF-8")
+      @buffer.appendString(str, enc)
+      self
+    end
+
+    # Sets bytes in the buffer to a representation of a FixNum. The buffer will expand as necessary to accomodate any bytes written.
+    # @param pos [FixNum] - the position in the buffer from where to start writing the FixNum
+    # @param num [FixNum]  - the FixNum to write
+    # @param bytes [FixNum] - the number of bytes to write to represent the FixNum. Valid values are 1, 2, 4, and 8
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def set_fixnum(pos, num, bytes)
+      case bytes
+        when 1
+          @buffer.setByte(pos, num)
+        when 2
+          @buffer.setShort(pos, num)
+        when 4
+          @buffer.setInt(pos, num)
+        when 8
+          @buffer.setLong(pos, num)
+        else
+          raise "bytes must be 1, 2, 4, or 8"
+      end
+      self
+    end
+
+    # Sets bytes in the buffer to a representation of a Float. The buffer will expand as necessary to accomodate any bytes written.
+    # @param pos [FixNum] - the position in the buffer from where to start writing the Float
+    # @param num [Float]  - the Float to write
+    # @param bytes [FixNum] - the number of bytes to write to represent the Float. Valid values are 4 and 8
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def set_float(pos, num, bytes)
+      case bytes
+        when 4
+          @buffer.setFloat(pos, num)
+        when 8
+          @buffer.setDouble(pos, num)
+        else
+          raise "bytes must be 4 or 8"
+      end
+      self
+    end
+
+    # Sets bytes in this buffer to the bytes of the specified buffer. The buffer will expand as necessary to accomodate any bytes written.
+    # @param pos [FixNum] - the position in this buffer from where to start writing the buffer
+    # @param buff [Buffer] - the buffer to write into this buffer
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def set_buffer(pos, buff)
+      @buffer.setBytes(pos, buff._to_java_buffer)
+      self
+    end
+
+    # Set bytes in the buffer to the string encoding in the specified encoding
+    # @param pos [FixNum] - the position in this buffer from where to start writing the string
+    # @param str [String] the string
+    # @param enc [String] the encoding
+    # @return [Buffer] a reference to self so multiple operations can be appended together.
+    def set_string(pos, str, enc = 'UTF-8')
+      @buffer.setString(pos, str, enc)
+      self
+    end
+
+    # @return [FixNum] the length of this buffer, in bytes.
+    def length
+      @buffer.length
+    end
+
+    # Get a copy of the entire buffer.
+    # @return [Buffer] the copy
+    def copy
+      Buffer.new(@buffer.copy())
+    end
+
+    # @private
+    def _to_java_buffer
+      @buffer
+    end
+
+  end
+end

data/lib/vertx/event_bus.rb

@@ -0,0 +1,206 @@
+# Copyright 2011 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'rubygems'
+require 'json'
+
+module Vertx
+
+  # This class represents a distributed lightweight event bus which can encompass multiple vert.x instances.
+  # It is very useful for otherwise isolated vert.x application instances to communicate with each other.
+  #
+  # The event bus implements both publish / subscribe network and point to point messaging.
+  #
+  # For publish / subscribe, messages can be published to an address using one of the publish methods. An
+  # address is a simple String instance. Handlers are registered against an address. There can be multiple handlers
+  # registered against each address, and a particular handler can be registered against multiple addresses.
+  # The event bus will route a sent message to all handlers which are registered against that address.
+
+  # For point to point messaging, messages can be sent to an address using the send method.
+  # The messages will be delivered to a single handler, if one is registered on that address. If more than one
+  # handler is registered on the same address, Vert.x will choose one and deliver the message to that. Vert.x will
+  # aim to fairly distribute messages in a round-robin way, but does not guarantee strict round-robin under all
+  # circumstances.
+  #
+  # All messages sent over the bus are transient. On event of failure of all or part of the event bus messages
+  # may be lost. Applications should be coded to cope with lost messages, e.g. by resending them,
+  # and making application services idempotent.
+  #
+  # The order of messages received by any specific handler from a specific sender should match the order of messages
+  # sent from that sender.
+  #
+  # When sending a message, a reply handler can be provided. If so, it will be called when the reply from the receiver
+  # has been received. Reply messages can also be replied to, etc, ad infinitum.
+  #
+  # Different event bus instances can be clustered together over a network, to give a single logical event bus.
+  #
+  # When receiving a message in a handler the received object is an instance of EventBus::Message - this contains
+  # the actual message plus a reply method which can be used to reply to it.
+  #
+  # @author {http://tfox.org Tim Fox}
+  class EventBus
+
+    @@handler_map = {}
+
+    @@j_eventbus = org.jruby.jubilee.vertx.JubileeVertx.vertx().eventBus()
+
+    # Send a message on the event bus
+    # @param message [Hash] The message to send
+    # @param reply_handler [Block] An optional reply handler.
+    # It will be called when the reply from a receiver is received.
+    def EventBus.send(address, message, &reply_handler)
+      EventBus.send_or_pub(true, address, message, reply_handler)
+      self
+    end
+
+    # Publish a message on the event bus
+    # @param message [Hash] The message to publish
+    def EventBus.publish(address, message)
+      EventBus.send_or_pub(false, address, message)
+      self
+    end
+
+    # @private
+    def EventBus.send_or_pub(send, address, message, reply_handler = nil)
+      raise "An address must be specified" if !address
+      raise "A message must be specified" if message == nil
+      message = convert_msg(message)
+      if send
+        if reply_handler != nil
+          @@j_eventbus.send(address, message, InternalHandler.new(reply_handler))
+        else
+          @@j_eventbus.send(address, message)
+        end
+      else
+        @@j_eventbus.publish(address, message)
+      end
+      self
+    end
+
+    # Register a handler.
+    # @param address [String] The address to register for. Messages sent to that address will be
+    # received by the handler. A single handler can be registered against many addresses.
+    # @param local_only [Boolean] If true then handler won't be propagated across cluster
+    # @param message_hndlr [Block] The handler
+    # @return [FixNum] id of the handler which can be used in {EventBus.unregister_handler}
+    def EventBus.register_handler(address, local_only = false, &message_hndlr)
+      raise "An address must be specified" if !address
+      raise "A message handler must be specified" if !message_hndlr
+      internal = InternalHandler.new(message_hndlr)
+      if local_only
+        @@j_eventbus.registerLocalHandler(address, internal)
+      else
+        @@j_eventbus.registerHandler(address, internal)
+      end
+      id = java.util.UUID.randomUUID.toString
+      @@handler_map[id] = [address, internal]
+      id
+    end
+
+    # Registers a handler against a uniquely generated address, the address is returned as the id
+    # received by the handler. A single handler can be registered against many addresses.
+    # @param local_only [Boolean] If true then handler won't be propagated across cluster
+    # @param message_hndlr [Block] The handler
+    # @return [FixNum] id of the handler which can be used in {EventBus.unregister_handler}
+    def EventBus.register_simple_handler(local_only = false, &message_hndlr)
+      raise "A message handler must be specified" if !message_hndlr
+      internal = InternalHandler.new(message_hndlr)
+      id = java.util.UUID.randomUUID.toString
+      if local_only
+        @@j_eventbus.registerLocalHandler(id, internal)
+      else
+        @@j_eventbus.registerHandler(id, internal)
+      end
+      @@handler_map[id] = [id, internal]
+      id
+    end
+
+    # Unregisters a handler
+    # @param handler_id [FixNum] The id of the handler to unregister. Returned from {EventBus.register_handler}
+    def EventBus.unregister_handler(handler_id)
+      raise "A handler_id must be specified" if !handler_id
+      tuple = @@handler_map.delete(handler_id)
+      raise "Cannot find handler for id #{handler_id}" if !tuple
+      @@j_eventbus.unregisterHandler(tuple.first, tuple.last)
+      self
+    end
+
+    # @private
+    def EventBus.convert_msg(message)
+      if message.is_a? Hash
+        message = org.vertx.java.core.json.JsonObject.new(JSON.generate(message))
+      elsif message.is_a? Buffer
+        message = message._to_java_buffer
+      elsif message.is_a? Fixnum
+        message = java.lang.Long.new(message)
+      elsif message.is_a? Float
+        message = java.lang.Double.new(message)
+      end
+      message
+    end
+
+  end
+
+  # @private
+  class InternalHandler
+    include org.vertx.java.core.Handler
+
+    def initialize(hndlr)
+      @hndlr = hndlr
+    end
+
+    def handle(message)
+      @hndlr.call(Message.new(message))
+    end
+  end
+
+  # Represents a message received from the event bus
+  # @author {http://tfox.org Tim Fox}
+  class Message
+
+    attr_reader :body
+
+    # @private
+    def initialize(message)
+
+      @j_del = message
+      if message.body.is_a? org.vertx.java.core.json.JsonObject
+        @body = JSON.parse(message.body.encode)
+      elsif message.body.is_a? org.vertx.java.core.buffer.Buffer
+        @body = Buffer.new(message.body)
+      else
+        @body = message.body
+      end
+    end
+
+    # Reply to this message. If the message was sent specifying a receipt handler, that handler will be
+    # called when it has received a reply. If the message wasn't sent specifying a receipt handler
+    # this method does nothing.
+    # Replying to a message this way is equivalent to sending a message to an address which is the same as the message id
+    # of the original message.
+    # @param [Hash] Message send as reply
+    def reply(reply, &reply_handler)
+      raise "A reply message must be specified" if reply == nil
+      reply = EventBus.convert_msg(reply)
+      if reply_handler != nil
+        @j_del.reply(reply, InternalHandler.new(reply_handler))
+      else
+        @j_del.reply(reply)
+      end
+    end
+
+  end
+
+end
+

data/lib/vertx/shared_data.rb

@@ -0,0 +1,214 @@
+# Copyright 2011 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'delegate'
+
+module Vertx
+
+  # Sometimes it is desirable to share immutable data between different event loops, for example to implement a
+  # cache of data.
+  #
+  # This class allows data structures to be looked up and used from different event loops.
+  # The data structures themselves will only allow certain data types to be stored into them. This shields the
+  # user from worrying about any thread safety issues might occur if mutable objects were shared between event loops.
+  #
+  # The following types can be stored in a shareddata data structure:
+  #
+  #   String
+  #   FixNum
+  #   Float
+  #   {Buffer} this will be automatically copied, and the copy will be stored in the structure.
+  #
+  # @author {http://tfox.org Tim Fox}
+  class SharedData
+
+    @@j_sd = org.jruby.jubilee.vertx.JubileeVertx.vertx().sharedData()
+
+    # Return a Hash with the specific name. All invocations of this method with the same value of name
+    # are guaranteed to return the same Hash instance.
+    # @param [String] key. Get the hash with the key.
+    # @return [Hash] the hash.
+    def SharedData.get_hash(key)
+      map = @@j_sd.getMap(key)
+      SharedHash.new(map)
+    end
+
+    # Return a Set with the specific name. All invocations of this method with the same value of name
+    # are guaranteed to return the same Set instance.
+    # @param [String] key. Get the set with the key.
+    # @return [SharedSet] the set.
+    def SharedData.get_set(key)
+      set = @@j_sd.getSet(key)
+      SharedSet.new(set)
+    end
+
+    # Remove the hash
+    # @param [String] key. The key of the hash.
+    def SharedData.remove_hash(key)
+      @@j_sd.removeMap(key)
+    end
+
+    # Remove the set
+    # @param [String] key. The key of the set.
+    def SharedData.remove_set(key)
+      @@j_sd.removeSet(key)
+    end
+
+    # Convert to corresponding Java objects
+    # And make copies where appropriate (the underlying java map will also make copies for some data types too)
+    # @private
+    def SharedData.check_obj(obj)
+      if obj.is_a?(Buffer)
+        obj = obj._to_java_buffer
+      end
+      obj
+    end
+
+    # @private
+    class SharedHash < DelegateClass(Hash)
+
+      def initialize(hash)
+        @hash = hash
+        # Pass the object to be delegated to the superclass.
+        super(@hash)
+      end
+
+      def []=(key, val)
+        key = SharedData.check_obj(key)
+        val = SharedData.check_obj(val)
+        super(key, val)
+      end
+
+      alias store []=
+
+      def [](key)
+        # We call the java class directly
+        obj = @hash.get(key)
+        obj = Buffer.new(obj) if obj.is_a? org.vertx.java.core.buffer.Buffer
+        obj
+      end
+
+      def ==(other)
+        if other.is_a?(SharedHash)
+          @hash.equal?(other._to_java_map)
+        else
+          false
+        end
+      end
+
+      def _to_java_map
+        @hash
+      end
+
+    end
+
+    #
+    # @private
+    class SharedSet
+
+      # @private
+      def initialize(j_set)
+        @j_set = j_set
+      end
+
+      def ==(other)
+        if other.is_a?(SharedSet)
+          @j_set.equal?(other._to_java_set)
+        else
+          false
+        end
+      end
+
+      # Add an object to the set
+      # @param [Object] obj. The object to add
+      # @return [SharedSet} self
+      def add(obj)
+        obj = SharedData.check_obj(obj)
+        @j_set.add(obj)
+        self
+      end
+
+      # Add an object to the set
+      # @param [Object] obj. The object to add
+      # @return [SharedSet] self if the object is not already in the set, otherwise nil
+      def add?(obj)
+        obj = SharedData.check_obj(obj)
+        if !@j_set.contains(obj)
+          @j_set.add(obj)
+          self
+        else
+          nil
+        end
+      end
+
+      # Clear the set
+      def clear
+        @j_set.clear
+      end
+
+      # Delete an object from the set
+      # @param [Object] obj. The object to delete
+      def delete(obj)
+        @j_set.remove(obj)
+      end
+
+      # Delete an object from the set
+      # @param [Object] obj. The object to delete
+      # @return [SharedSet] self if the object was in the set before the remove, nil otherwise.
+      def delete?(obj)
+        if @j_set.contains(obj)
+          @j_set.remove(obj)
+          self
+        else
+          nil
+        end
+      end
+
+      # Call the block for every element of the set
+      # @param [Blovk] block. The block to call.
+      def each(&block)
+        iter = @j_set.iterator
+        while iter.hasNext do
+          obj = iter.next
+          obj = Buffer.new(obj) if obj.is_a? org.vertx.java.core.buffer.Buffer
+          block.call(obj)
+        end
+      end
+
+      # @return [Boolean] true if the set is empty
+      def empty?
+        @j_set.isEmpty
+      end
+
+      # Does the set contain an element?
+      # @param [Object] obj, the object to check if the set contains
+      # @return [Boolean] true if the object is contained in the set
+      def include?(obj)
+        obj = obj._to_java_buffer if obj.is_a? Buffer
+        @j_set.contains(obj)
+      end
+
+      # @return [FixNum] The number of elements in the set
+      def size
+        @j_set.size
+      end
+
+      # @private
+      def _to_java_set
+        @j_set
+      end
+
+    end
+  end
+end

data/lib/vertx.rb

@@ -0,0 +1,26 @@
+# Copyright 2011 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+include Java
+
+require 'vertx/buffer'
+require 'vertx/event_bus'
+
+# This is the module for vertx related feature like EventBus and SharedData,
+# these features are built into jubilee server, by requiring 'vertx' in your
+# rack application, you get access to the functionalities offered by vertx
+# platform.
+
+module Vertx
+end