Module: EPIC::HS

Defined in:
src/epic_hs.rb

Overview

Namespace for everything related to the Handle System client library (Java).

This module is not object-oriented; it’s just a collection of “procedures” that wrap around bits of the Handle client library.

Constant Summary

HDLLIB =

A shorthand for the Java net.handle.hdllib package. 

Java::NetHandleHdllib
PERMS_BY_I =

All permissions in the Handle System, indexed by integers. 

[
  'add_handle',          #  0
  'delete_handle',       #  1
  'add_naming_auth',     #  2
  'delete_naming_auth',  #  3
  'modify_value',        #  4
  'remove_value',        #  5
  'add_value',           #  6
  'read_value',          #  7
  'modify_admin',        #  8
  'remove_admin',        #  9
  'add_admin',           # 10
  'list_handles'         # 11
]
PERMS_BY_S =

All permissions in the Handle System, indexed by symbols. 

Hash[ PERMS_BY_I.each_with_index.to_a ]
AUTHINFO =

Cache of Java AuthenticationInfo objects, indexed by user name. 

{}
MUTEX =

Mutex used to make some of the methods in this class thread-safe.

See Also:

Mutex.new
EMPTY_HANDLE_VALUE = 
HDLLIB::HandleValue.new

Class Method Summary (collapse)

Class Method Details

+ (HDLLIB::AuthenticationInfo) authentication_info(user_name)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A Java AuthenticationInfo object for user user_name.

The objects are cached for efficiency, in class constant AUTH_INFO

Parameters:

  • user_name (#to_s)

Returns:

  • (HDLLIB::AuthenticationInfo) 


237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'src/epic_hs.rb', line 237

def authentication_info user_name
  user_name = user_name.to_s
  unless AUTHINFO[user_name]
    userInfo = EPIC::USERS[user_name]
    raise "No user info found for user '#{user_name}'" unless userInfo
    MUTEX.synchronize do
      #TODO Public key authentication
      AUTHINFO[user_name] ||= HDLLIB::SecretKeyAuthenticationInfo.new(
        userInfo[:handle].to_java_bytes,
        userInfo[:index],
        userInfo[:secret].to_java_bytes,
        true
      )
    end
  end
  AUTHINFO[user_name]
end

+ create_handle(handle, values, user_name)

This method returns an undefined value.

Create a Handle

Parameters:

  • handle (#to_s)
  • values (Array<HandleValue>)
  • user_name (#to_s)

Raises:



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'src/epic_hs.rb', line 262

def create_handle handle, values, user_name
  values = values.collect do
    |value|
    value.handle_value
  end
  request = HDLLIB::CreateHandleRequest.new(
    handle.to_java_bytes,
    values.to_java( HDLLIB::HandleValue ),
    authentication_info( user_name )
  )
  response = resolver.processRequest( request )
  if response.kind_of? HDLLIB::ErrorResponse
    case response.responseCode
    when HDLLIB::ErrorResponse::RC_INSUFFICIENT_PERMISSIONS,
         HDLLIB::ErrorResponse::RC_INVALID_ADMIN
      raise Rackful::HTTP403Forbidden
    else
      raise response.to_string
    end
  end
end

+ delete_handle(handle, user_name)

This method returns an undefined value.

Deletes a Handle

Parameters:

  • handle (#to_s)
  • user_name (#to_s)

Raises:



381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
 
# File 'src/epic_hs.rb', line 381

def delete_handle handle, user_name
  authInfo = authentication_info( user_name )
  request = HDLLIB::DeleteHandleRequest.new(
    handle.to_java_bytes,
    authInfo
  )
  response = resolver.processRequest( request )
  if response.kind_of? HDLLIB::ErrorResponse
    case response.responseCode
    when HDLLIB::ErrorResponse::RC_INSUFFICIENT_PERMISSIONS,
         HDLLIB::ErrorResponse::RC_INVALID_ADMIN
      raise Rackful::HTTP403Forbidden
    when HDLLIB::ErrorResponse::RC_HANDLE_NOT_FOUND
      raise Rackful::HTTP404NotFound
    else
      raise response.to_string
    end
  end
end

+ (String) pack_HS_ADMIN(data)

Parameters:

  • data (Hash)

Returns:

Raises:

See Also:

  • #pack_SOME_HANDLE_TYPE


149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'src/epic_hs.rb', line 149

def pack_HS_ADMIN data
  raise Rackful::HTTP400BadRequest, "Missing one or more required values: #{data.inspect}" \
    if ! data.kind_of?( Hash ) ||
       ! data[:adminId] ||
       ! data[:adminIdIndex] ||
       ! data[:perms] ||
       ! data[:perms].kind_of?( Hash ) ||
       ! PERMS_BY_I.all? {
           |perm|
           data[:perms].key? perm.to_sym
         }
  adminRecord = HDLLIB::AdminRecord.new
  adminRecord.adminId =
    data[:adminId].to_s.force_encoding(Encoding::ASCII_8BIT).to_java_bytes
  adminRecord.adminIdIndex = data[:adminIdIndex].to_i
  adminRecord.perms = PERMS_BY_I.collect do
    |perm|
    !! data[:perms][ perm.to_sym ]
  end.to_java Java::boolean
  String.from_java_bytes(
    HDLLIB::Encoder.encodeAdminRecord( adminRecord )
  )
end

+ (String) pack_HS_VLIST(data)

Parameters:

  • data (Hash)

Returns:

See Also:

  • #pack_SOME_HANDLE_TYPE


191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
 
# File 'src/epic_hs.rb', line 191

def pack_HS_VLIST data
  raise 'Bad HS_VLIST data.' \
    if ! data.kind_of?( Array ) ||
       ! data.all? {
         |ref|
         ref.kind_of?(Hash) &&
         ref[:idx] &&
         ref[:idx].respond_to?(:to_i) &&
         ref[:handle] &&
         ref[:handle].respond_to?(:to_s)
       }
  data = data.collect do
    |ref|
    HS::HDLLIB::ValueReference.new(
      ref[:handle].to_s.to_java_bytes,
      ref[:idx].to_i
    )
  end.to_java HS::HDLLIB::ValueReference
  String.from_java_bytes(
    HDLLIB::Encoder.encodeValueReferenceList( data )
  )
end

+ (String) pack_SOME_HANDLE_TYPE(data)

Translates a Ruby structure into binary data.

Parameters:

  • data (Hash) —

    some structured data

Returns:

  • (String) —

    a binary representation of data

See Also:

  • #unpack_SOME_HANDLE_TYPE



# File 'src/epic_hs.rb', line 117

+ (void) resolver

HandleResolver should be thread safe, so there’s only one of it. 



216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'src/epic_hs.rb', line 216

def resolver
  unless class_variable_defined? :@@resolver
    MUTEX.synchronize do
      unless class_variable_defined? :@@resolver
        @@resolver = HDLLIB::HandleResolver.new
        sessionSetupInfo = HDLLIB::SessionSetupInfo.new nil
        clientSessionTracker = HDLLIB::ClientSessionTracker.new sessionSetupInfo
        @@resolver.setSessionTracker clientSessionTracker
      end
    end
  end
  @@resolver
end

+ (Hash) unpack_HS_ADMIN(data)

Parameters:

Returns:

  • (Hash)

See Also:

  • #unpack_SOME_HANDLE_TYPE


127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'src/epic_hs.rb', line 127

def unpack_HS_ADMIN data
  adminRecord = HDLLIB::AdminRecord.new
  HDLLIB::Encoder.decodeAdminRecord(
    data.to_java_bytes, 0, adminRecord
  )
  perms = adminRecord.perms.to_a
  {
    :adminId => String.from_java_bytes( adminRecord.adminId ).force_encoding(Encoding::UTF_8),
    :adminIdIndex => adminRecord.adminIdIndex,
    :perms => Hash[
      perms.each_index.collect {
        |i|
        [ PERMS_BY_I[i], perms[i] ] 
      }
    ]
  }
end

+ (Hash) unpack_HS_VLIST(data)

Parameters:

Returns:

  • (Hash)

See Also:

  • #unpack_SOME_HANDLE_TYPE


177
178
179
180
181
182
183
184
185
 
# File 'src/epic_hs.rb', line 177

def unpack_HS_VLIST data
  vlist = HDLLIB::Encoder.decodeValueReferenceList(
    data.to_java_bytes, 0
  )
  vlist.to_a.collect do
    |ref|
    { :idx => ref.index, :handle => String.from_java_bytes( ref.handle ) }
  end
end

+ (Hash) unpack_SOME_HANDLE_TYPE(data)

Translates binary data (from the database) to a Ruby structure.

For certain binary encoded Handle value types, like HS_ADMIN and HS_VLIST, the web service can produce and consume a structured representation. For example, the JSON representation of an HS_ADMIN value looks like this (abbreviated and prettified for clarity): 


  {
    "idx"        : 100,
    "type"       : "HS_ADMIN",
    "data"       : "D/8AAAAKMC5OQS8xMTAyMgAAASwAAA==",
    "parsed_data": {
      "adminId"     : "0.NA/11022",
      "adminIdIndex": 300,
      "perms"       : {
           "add_handle": true,     "add_naming_auth": true,
        "delete_handle": true,  "delete_naming_auth": true,
         "modify_value": true,        "modify_admin": true,
         "remove_value": true,        "remove_admin": true,
            "add_value": true,           "add_admin": true,
           "read_value": true,        "list_handles": true
      }
    }
  }

To add a new “parseble” type to this web service, all you have to do is create two new methods in this module, called unpack_YOUR_TYPE and pack_YOUR_TYPE, which translate between the binary and the structured representations.

See also:

EPIC::HandleValue#parsed_data and EPIC::HandleValue#parsed_data= which use introspection to find out if a parsed representation of a value type is available.

Parameters:

  • data (String) —

    some binary data.

Returns:

  • (Hash) —

    a structured representation of data 




# File 'src/epic_hs.rb', line 77

+ update_handle(handle, old_values, new_values, user_name)

This method returns an undefined value.

Update a Handle

Parameters:

  • handle (#to_s)
  • old_values (Array<HandleValue>) —

    The old values in handle.

  • new_values (Array<HandleValue>) —

    The new values for handle.

  • user_name (#to_s)

Raises:



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'src/epic_hs.rb', line 292

def update_handle handle, old_values, new_values, user_name
  authInfo = authentication_info( user_name )
  values_2b_added    = []
  values_2b_modified = []
  values_2b_removed  = []
  new_values.each do
    |new_value|
    # If the passed handle value is equal to the existing handle value in all
    # respects, and no timestamp is passed, then the old timestamp should be
    # used.
    old_value = old_values.find do
      |old_value|
      old_value.idx == new_value.idx
    end
    if ! old_value
      values_2b_added << new_value.handle_value
    elsif old_value and
        old_value.type != new_value.type ||
        old_value.data != new_value.data ||
        old_value.ttl_type != new_value.ttl_type ||
        old_value.ttl != new_value.ttl ||
        old_value.refs.any? do
            |ref1|
            new_value.refs.none? do
              |ref2|
              ref1[:idx]    == ref2[:idx] &&
              ref1[:handle] == ref2[:handle]
            end # new_value.refs.any? do
          end || #old_value.refs.all? do
        new_value.refs.any? do
            |ref1|
            old_value.refs.none? do
              |ref2|
              ref1[:idx]    == ref2[:idx] &&
              ref1[:handle] == ref2[:handle]
            end # old_value.refs.any?
          end # new_value.refs.all? do
      values_2b_modified << new_value.handle_value
    end
  end
  old_values.each do
    |old_value|
    if new_values.none? { |new_value| new_value.idx == old_value.idx }
      values_2b_removed << old_value.idx
    end
  end
  requests = []
  if ! values_2b_added.empty?
    requests << HDLLIB::AddValueRequest.new(
      handle.to_java_bytes,
      values_2b_added.to_java( HDLLIB::HandleValue ),
      authentication_info( user_name )
    )
  end
  if ! values_2b_modified.empty?
    requests << HDLLIB::ModifyValueRequest.new(
      handle.to_java_bytes,
      values_2b_modified.to_java( HDLLIB::HandleValue ),
      authentication_info( user_name )
    )
  end
  if ! values_2b_removed.empty?
    requests << HDLLIB::RemoveValueRequest.new(
      handle.to_java_bytes,
      values_2b_removed.to_java( Java::int ),
      authentication_info( user_name )
    )
  end
  requests.each do
    |request|
    response = resolver.processRequest( request )
    if response.kind_of? HDLLIB::ErrorResponse
      case response.responseCode
      when HDLLIB::ErrorResponse::RC_INSUFFICIENT_PERMISSIONS,
           HDLLIB::ErrorResponse::RC_INVALID_ADMIN
        raise Rackful::HTTP403Forbidden
      else
        raise response.to_string
      end
    end
  end
end