Class: RSence::HValue

Inherits:
Object
  • Object
show all
Defined in:
lib/rsence/value.rb

Overview

HValue is the model for client-server synchronized values. A value contains its payload #data and enough meta-data to define its behavior.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(msg, data, meta = { :name => nil }) ⇒ HValue

Creates a new client-server automatically synchronized data wrapper object.

Parameters:

  • msg (Message) —

    Just pass on the msg from the scope you call from.

  • data (#to_json) —

    Any data that can be converted to JSON.

  • meta (Hash) (defaults to: { :name => nil }) —

    Has no effect yet.



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/rsence/value.rb', line 81

def initialize( msg, data, meta = { :name => nil } )
  
  ## Get an unique integer id for the value
  if RSence.args[:debug] and meta[:name] and not msg.valuemanager.id_exists?( msg, meta[:name] )
    @value_id   = meta[:name]
  else
    @value_id = msg.valuemanager.ses_unique_id( msg )
  end
  
  @meta = meta
  
  ## set the data of the hvalue
  set( msg, data, true )
  
  ## the @sync flag is raised, when the client data is older than the server data
  @sync  = false
  
  ## the @is_valid flag is lowered, when the client data is newer than the server data
  @is_valid = true
  
  ## Bind the value to the value manager and report it to the client
  add( msg )
  
  ## storage for validator bindings
  @members = {}
  
end

Instance Attribute Details

#data ⇒ Object (readonly)

The payload data. Use #set to change.



30
31
32
 
# File 'lib/rsence/value.rb', line 30

def data
  @data
end

#is_valid ⇒ Boolean Also known as: valid, valid?

The validity of the data. Defaults to false, when the data comes from the client.

Returns:

  • (Boolean) —

    True, when set by the server. False when initially set by the client. Also false, unless all responders return true.



20
21
22
 
# File 'lib/rsence/value.rb', line 20

def is_valid
  @is_valid
end

#meta ⇒ Object

Value meta-data. The third constructor parameter



75
76
77
 
# File 'lib/rsence/value.rb', line 75

def meta
  @meta
end

Instance Method Details

#bind(plugin_name, method_name) ⇒ true

Binds the value to a responder. The responder is an instance of Plugin or GUIPlugin. Responders are called once, when the client requests the data to be changed. Responders must return true, if they accept the change. Otherwise the data is treated as invalid. Responders must respond to exactly two parameters: ( (Message) msg, (HValue) value )

Parameters:

  • plugin_name (Symbol) —

    The name of the registered plugin to call with the method_name

  • method_name (Symbol) —

    The name of the method of the registered plugin plugin_name to call.

Returns:

  • (true) 


117
118
119
120
121
122
123
 
# File 'lib/rsence/value.rb', line 117

def bind( plugin_name, method_name )
  plugin_name = plugin_name.to_sym unless plugin_name.class == Symbol
  method_name = method_name.to_sym unless method_name.class == Symbol
  @members[plugin_name] = [] unless @members.has_key?( plugin_name )
  @members[plugin_name].push( method_name ) unless @members[plugin_name].include?( method_name )
  return true
end

#bound?(plugin_name, method_name) ⇒ Boolean

Checks, if the plugin_name and method_name pairing is already bound with the bind method. Returns true or false.

Returns:

  • (Boolean) 


126
127
128
129
130
131
 
# File 'lib/rsence/value.rb', line 126

def bound?( plugin_name, method_name )
  plugin_name = plugin_name.to_sym unless plugin_name.class == Symbol
  method_name = method_name.to_sym unless method_name.class == Symbol
  return false unless @members.has_key?(plugin_name)
  return @members[plugin_name].include?(method_name)
end

#die!(msg = false) ⇒ Object Also known as: die

Destructor method. If msg is supplied, deletes the client representation too.

Parameters:

  • A (false, Message) —

    Message instance. When supplied, deletes the client representation.



259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/rsence/value.rb', line 259

def die!( msg=false )
  
  release_all
  
  # get the value storage from the session data
  session_values = msg.session[:values][:by_id]
  
  ## Store the object here
  session_values.delete( @value_id )
  
  if msg and not @is_new_to_client
    msg.reply_value( :del, @value_id )
  end
end

#inspect ⇒ Object 



275
276
277
 
# File 'lib/rsence/value.rb', line 275

def inspect
  "#<RSence::HValue value_id:#{@value_id.inspect}, valid: #{@is_valid.inspect}, sync: #{@sync.inspect}, is_new_to_client: #{@is_new_to_client.inspect}, meta: #{@meta.inspect[0..100]}, data: #{@data.inspect[0..100]} ...>"
end

#release(plugin_name = false, method_name = false) ⇒ Boolean Also known as: unbind

Releases the responder of the value, both params as in bind, but optional method_name can be omitted, matching all methods bound to the plugin_name.

Parameters:

  • plugin_name (Symbol) (defaults to: false) —

    The name of the plugin acting as a responder to the value.

  • method_name (Symbol) (defaults to: false) —

    The name of the method of the plugin acting as a responder to the value.

Returns:

  • (Boolean) —

    Returns true, if successful, false if not bound or other error.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'lib/rsence/value.rb', line 137

def release( plugin_name=false, method_name=false )
  plugin_name = plugin_name.to_sym if plugin_name.class == String
  method_name = method_name.to_sym if method_name.class == String
  return release_all if not plugin_name and not method_name
  return false unless @members.has_key?( plugin_name )
  if not method_name
    @members.delete( plugin_name )
  else 
    @members[plugin_name].slice!(@members[plugin_name].index( method_name )) if @members[plugin_name].include?(method_name)
    if @members[plugin_name].empty?
      @members.delete( plugin_name )
    end
  end
  return true
end

#release_all ⇒ true

Releases all responders.

Returns:

  • (true) 


155
156
157
158
 
# File 'lib/rsence/value.rb', line 155

def release_all
  @members = {}
  return true
end

#set(msg, data, dont_tell_client = false) ⇒ Object

Sets the data of the value, the change will be synced with the client.

Parameters:

  • msg (Message) —

    The Message instance.

  • data (#to_json) —

    Any data that can be mapped to JSON and handled by the client.

  • dont_tell_client (Boolean) (defaults to: false) —

    Doesn’t notify the client about the change, if true.



212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/rsence/value.rb', line 212

def set( msg, data, dont_tell_client=false )
  
  @data   = data
  
  # won't tell the client about the change, usually not needed
  unless dont_tell_client
    ## update the flags
    @sync  = false
    @is_valid = true
    
    add_to_sync( msg )
  end
end

#set_key(msg, key, data, dont_tell_client = false) ⇒ Object

Sets the key of the hash data of the value, the change will be synced with the client.

Parameters:

  • msg (Message) —

    The Message instance.

  • key (String) —

    The key of data to change

  • data (#to_json) —

    Any data that can be mapped to JSON and handled by the client.

  • dont_tell_client (Boolean) (defaults to: false) —

    Doesn’t notify the client about the change, if true.



231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/rsence/value.rb', line 231

def set_key( msg, key, data, dont_tell_client=false )
  
  @data[key] = data
  
  # won't tell the client about the change, usually not needed
  unless dont_tell_client
    ## update the flags
    @sync  = false
    @is_valid = true
    
    add_to_sync( msg )
  end
end