class RSence::Message

A Message instance is used as a ‘messenger class` while processing client-server requests. It’s initialized by the system and the convention guideline for its instance is msg, pass it on wherever msg might be needed. In most cases, the use of msg is to just pass the same msg onward from a method to another.

@example Logs a message in the client javascript console.

msg.console "#{Time.new.to_s} -- Testing.."

@example Executes a custom Javascript command in the client.

msg.reply "alert('Hello!');"

@example Invalidates the session.

msg.expire_session

@example Creating a new {HValue}. Usage like this in any extended {Plugins::Plugin__ Plugin} or {Plugins::GUIPlugin__ GUIPlugin} class. It’s recommended to use the values.yaml file to create any initial values.

def create_example_value( msg )
  ses = get_ses(msg)
  default_data = "Some text"
  if ses.has_key?( :example_value )
    # Resets the default data, causes it to update in the client too on the next sync.
    ses[:example_value].set( msg, default_data )
  else
    # Creates a new value with default data
    ses[:example_value] = HValue.new( msg, default_data )
  end
end

Attributes

buffer[RW]

@private Response output buffer, Array of Strings; sent to client using to_json

cloned_source[RW]

Contains the source ses on the first request after the active session was cloned from another session. @return [false, Hash]

cloned_targets[RW]

Contains the target sessions packed in an Array on the first request after another session was cloned from the active session. @return [false, Array<Hash>]

new_session[RW]

Flag for a new session’s first request. Check it in your code to decide what to do, when a new session is encountered. In systems that require authentication, this may be used as a trigger to display a login/register dialog. @return [Boolean] This flag is true on the first request of a newly created session.

plugins[RW]

Reference to the main {PluginManager} @return [PluginManager]

request[RW]

The HTTP Request object of the active request. @return [Request]

response[RW]

The HTTP Response object of the active request. @return [Response]

response_success[RW]

@private The request success flag; Boolean.

restored_session[RW]

Flag for a restored session’s first request. Check it in your code to decide what to do, when a restored session is encountered. @return [Boolean] This flag is true on the first request of a newly restored session.

ses_valid[RW]

@private The session is not valid by default, it’s set by SessionManager, if everything seems ok.

session[RW]

@private Session data placeholder, assigned by SessionManager.

sessions[RW]

Reference to {SessionManager} @return [SessionManager]

transporter[RW]

Reference to {Transporter} @return [Transporter]

value_buffer[RW]

@private Value response output buffer, Array value setters; sent to client using to_json before {:buffer} is sent

valuemanager[RW]

Reference to {ValueManager} @return [ValueManager]

Public Class Methods

new( transporter, request, response, options ) click to toggle source

@private Message is initialized with a valid {Transporter}, {Request} and {Response} objects along with options.

# File lib/rsence/msg.rb, line 92
def initialize( transporter, request, response, options )

  @config = RSence.config

  @request  = request
  @response_success = false
  @response = response
  @session  = nil
  @buffer = []

  @options = options

  # Value response output.
  @value_buffer = {
    :new => [],
    :set => [],
    :del => []
  }

  # The session key placeholder.
  @ses_key = false
  @new_session      = false
  @restored_session = false
  @cloned_source = false
  @cloned_targets = false
  @ses_valid = false
  @error_js = ''

  # global instances
  @transporter    = transporter
  @valuemanager   = @transporter.valuemanager
  @sessions = @transporter.sessions
  @plugins  = @transporter.plugins

  if options[:servlet]
    @do_gzip = false
  else
    @response['Content-Type'] = 'application/json; charset=utf-8'
    @response['Cache-Control'] = 'no-cache'

    # gnu-zipped responses:
    if @request.header['accept-encoding'] and @request.header['accept-encoding'].include?('gzip') and not @config[:no_gzip]
      @response['Content-Encoding'] = 'gzip'
      @do_gzip = true
    else
      @do_gzip = false
    end
  end

  @response_sent = false
end

Public Instance Methods

buf_json(buffer) click to toggle source

@private Converts the buffer to JSON

# File lib/rsence/msg.rb, line 235
def buf_json(buffer)
  buffer.to_json
end
call( plugin_name, plugin_method, *args ) click to toggle source

Calls a method of a registered plugin with optional arguments. @param [Symbol] plugin_name The plugin to call @param [Symbol] plugin_method The method of the plugin to call @param *args Any arguments to pass to the ‘plugin_method`

# File lib/rsence/msg.rb, line 369
def call( plugin_name, plugin_method, *args )
  @plugins.call( plugin_name, plugin_method, *args)
end
Also aliased as: run
coffee(data) click to toggle source

Same as reply, but with CoffeeScript instead of JS

# File lib/rsence/msg.rb, line 292
def coffee(data)
  puts data if @config[:trace]
  @buffer.push( @plugins[:client_pkg].coffee( data ) )
end
console(data) click to toggle source

Sends data to the client’s javascript console. @param [#to_json] data Any data that can be presented in the Javascript console.

# File lib/rsence/msg.rb, line 312
def console(data)
  reply( "console.log(#{data.to_json});" )
end
Also aliased as: puts
error_msg( error_js ) click to toggle source

@private Sets the error message @param [String] error_js The error script to send instead of the regular buffers.

# File lib/rsence/msg.rb, line 229
def error_msg( error_js )
  @error_js = error_js
  # response_done
end
expire_session() click to toggle source

Invalidates the active session. @return [nil]

# File lib/rsence/msg.rb, line 146
def expire_session
  @sessions.expire_session( @session[:ses_id] ) if @session
end
inspect() click to toggle source
# File lib/rsence/msg.rb, line 374
def inspect
  "#<Message ses_id:#{ses_id.inspect}, ses_key: #{ses_key.inspect} ...>"
end
lang() click to toggle source

Getter for the user language @return [Hash] The current user language. Returns RSence.config[:lang] by default

# File lib/rsence/msg.rb, line 176
def lang
  uinfo = user_info
  uinfo[:lang] = RSence.config[:lang] unless uinfo.has_key? :lang
  uinfo[:lang]
end
lang=(lang) click to toggle source

Setter for the user language @param [String] lang The language to set. Use in login situations to store the user language. @return [nil]

# File lib/rsence/msg.rb, line 209
def lang=(lang)
  @session[:user_info][:lang] = lang
end
puts(data)
Alias for: console
refresh_page?( plugin_incr ) click to toggle source

@private used for automatic reload of page, when the plugins have been changed.

# File lib/rsence/msg.rb, line 183
def refresh_page?( plugin_incr )
  if plugin_incr != @session[:plugin_incr]
    puts "@session[:plugin_incr] = #{@session[:plugin_incr].inspect}  vs  plugin_incr = #{plugin_incr.inspect}" if RSence.args[:debug]
    @session[:plugin_incr] = plugin_incr
    return true
  end
  return false
end
release_rsrc( uri ) click to toggle source

Removes the URL served, you must call this manually when after a served resource is no longer needed! Calls the default ‘ticket` plugin. @see {#serve_rsrc} @param [String] uri The URL to delete; the return value of {#serve_rsrc} @deprecated Use {TicketPlugin#serve_rsrc ticket.serve_rsrc} directly instead.

# File lib/rsence/msg.rb, line 360
def release_rsrc( uri )
  call(:ticket,:del_rsrc, uri[3..-1] )
end
Also aliased as: unserve_rsrc
reply(data,dont_squeeze=false) click to toggle source

Sends data to the client, usually javascript, but is valid for any data that responds to to_json @param [String<js>, to_json] data Javascript source or object that responds to to_json @param [Boolean] dont_squeeze When true, doesn’t ‘squeeze` the contents (jsmin + jscompress)

# File lib/rsence/msg.rb, line 284
def reply(data,dont_squeeze=false)
  data.strip!
  data = @plugins[:client_pkg].squeeze( data ) unless dont_squeeze
  puts data if @config[:trace]
  @buffer.push( data )
end
reply_value( operation_type, value_id, data=nil, type=0 ) click to toggle source

@private For value manager; insert changed values BEFORE other js.

# File lib/rsence/msg.rb, line 298
def reply_value( operation_type, value_id, data=nil, type=0 )
  if operation_type == :set
    @value_buffer[:set].push( [ value_id, data ] )
  elsif operation_type == :new
    @value_buffer[:new].push( [ value_id, data, type ] )
  elsif operation_type == :del
    @value_buffer[:del].push( value_id )
  else
    throw "Invalid reply_value operation: operation_type: #{operation_type.inspect}, value_id: #{value_id.inspect}, data: #{data.inspect}"
  end
end
response_done() click to toggle source

@private Called to flush buffer.

# File lib/rsence/msg.rb, line 240
def response_done
  return if @response_sent
  if not @response_success
    @response.status = 200
    #@response.status = 503

    buffer = [
      "", # empty session key will stop the syncing
      {}, # no session values
    ] + @error_js
  else
    @session.delete( :_msg_unused ) if @session.has_key?( :_msg_unused )
    ## The response status should always be 200 (OK)
    @response.status = 200

    @value_buffer.delete( :new ) if @value_buffer[:new].empty?
    @value_buffer.delete( :set ) if @value_buffer[:set].empty?
    @value_buffer.delete( :del ) if @value_buffer[:del].empty?
    buffer = [
      @ses_key,
      @value_buffer,
    ] + @buffer

  end

  # flush the output
  if @do_gzip
    outp = GZString.new('')
    gzwriter = Zlib::GzipWriter.new(outp,Zlib::BEST_SPEED)
    gzwriter.write( buf_json(buffer) )
    gzwriter.close
  else
    outp = buf_json(buffer)
  end

  @response['Content-Length'] = outp.bytesize.to_s
  @response.body = outp

  @response_sent = true
end
run( plugin_name, plugin_method, *args )
Alias for: call
serve_file( file_data, content_type='text/plain', filename='untitled.txt' ) click to toggle source

Binary data to be served once as a downloadable file attachment, returns a disposable URL. Calls the default ‘ticket` plugin. @param [String] file_data The binary data to serve @param [String] content_type The MIME type to serve the data as @param [String] filename The name of the downloadable file. @return [String] The URL where the downloadable file can be accessed from using a GET request. @deprecated Use {TicketPlugin#serve_file ticket.serve_file} directly instead.

# File lib/rsence/msg.rb, line 336
def serve_file( file_data, content_type='text/plain', filename='untitled.txt' )
  call( :ticket, :serve_file, self, file_data, content_type, filename )
end
serve_img( img_obj, img_format='PNG' ) click to toggle source

Serves an image object and returns its disposable URL. Calls the default ‘ticket` plugin. @param [#to_blob] img_obj RMagick image object. @param [String] img_format The format img_obj#to_blob is encoded as. @return [String] The URL where the image can be accessed from using a GET request. @deprecated Use {TicketPlugin#serve_img ticket.serve_img} directly instead.

# File lib/rsence/msg.rb, line 324
def serve_img( img_obj, img_format='PNG' )
  call( :ticket, :serve_img, self, img_obj, img_format )
end
serve_rsrc( rsrc_data, content_type='text/plain' ) click to toggle source

Sends any binary to be served indefinitely, returns a unique, random, static URL. Calls the default ‘ticket` plugin. IMPORTANT: PLEASE call {#release_rsrc} manually, when the resource is no longer needed to free the memory occupied! HINT: In most cases, it’s a better idea to use serve_img or serve_file to expire the resource automatically. @see {#release_rsrc} @param [String] rsrc_data The binary data of the resource to serve. @param [String] content_type The MIME type to serve the data as @return [String] The URL where the resource can be accessed from using a GET request. @deprecated Use {TicketPlugin#serve_rsrc ticket.serve_rsrc} directly instead.

# File lib/rsence/msg.rb, line 350
def serve_rsrc( rsrc_data, content_type='text/plain' )
  call(:ticket,:serve_rsrc,self, rsrc_data, content_type )
end
ses_id() click to toggle source

Returns the session id @return [Number]

# File lib/rsence/msg.rb, line 215
def ses_id
  @session[:ses_id]
end
Also aliased as: session_id
ses_id=(ses_id) click to toggle source

@private Sets the session id @param [Number] ses_id The session id to set. @return [nil]

# File lib/rsence/msg.rb, line 223
def ses_id=(ses_id)
  @session[:ses_id] = ses_id
end
ses_key() click to toggle source

@private Getter for session key. @return [String] The active session key.

# File lib/rsence/msg.rb, line 157
def ses_key
  @ses_key
end
ses_key=(ses_key) click to toggle source

@private Define the session key.

# File lib/rsence/msg.rb, line 151
def ses_key=(ses_key)
  @ses_key = ses_key
end
session_id()
Alias for: ses_id
unserve_rsrc( uri )
Alias for: release_rsrc
user_id() click to toggle source

Getter for the user id @return [Number, String] The current user id. Returns 0 by default.

# File lib/rsence/msg.rb, line 163
def user_id
  @session[:user_id]
end
user_id=(user_id) click to toggle source

Setter for the user id @param [Number, String] user_id The user id to set. Use in login situations to store the user id. @return [nil]

# File lib/rsence/msg.rb, line 195
def user_id=(user_id)
  @session[:user_id] = user_id
end
user_info() click to toggle source

Getter for the user info hash @return [Hash] The current user info hash. Returns {} by default.

# File lib/rsence/msg.rb, line 169
def user_info
  @session[:user_info] = {} unless @session.has_key?(:user_info)
  @session[:user_info]
end
user_info=(user_info) click to toggle source

Setter for the user info @param [Hash] user_info The user info hash to set. Use in login situations to store the user information. @return [nil]

# File lib/rsence/msg.rb, line 202
def user_info=(user_info)
  @session[:user_info] = user_info
end