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, :type => 0 }) ⇒ 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, :type => 0 }) —

    Has no effect yet.



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/rsence/value.rb', line 72

def initialize( msg, data, meta = { :name => nil, :type => 0 } )

  ## 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

  if meta[:type] == 2
    @buffer = []
  end

  ## 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.



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

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.



11
12
13
 
# File 'lib/rsence/value.rb', line 11

def is_valid
  @is_valid
end

#meta ⇒ Object

Value meta-data. The third constructor parameter



66
67
68
 
# File 'lib/rsence/value.rb', line 66

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) 


112
113
114
115
116
117
118
 
# File 'lib/rsence/value.rb', line 112

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) 


121
122
123
124
125
126
 
# File 'lib/rsence/value.rb', line 121

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.



270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/rsence/value.rb', line 270

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 



286
287
288
 
# File 'lib/rsence/value.rb', line 286

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.



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/rsence/value.rb', line 132

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) 


150
151
152
153
 
# File 'lib/rsence/value.rb', line 150

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.



216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/rsence/value.rb', line 216

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
    @buffer.push( data ) if @meta[:type] == 2
    ## 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.



236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/rsence/value.rb', line 236

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