Class: Net::DND::Session

Inherits:
Object
  • Object
show all
Defined in:
lib/net/dnd/session.rb

Overview

This is the DND session object. It provides the high-level interface for performing lookup-style searches against a given DND host. It manages the Connection object, which is the low-level socket stuff, and sends back DND Profile objects, either singly or an array, as the result of the find method.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host) ⇒ Session

Constructor method. Only called directly by unit tests (specs). The start method handles the setting up of a full DND session.

Raises:



22
23
24
25
 
# File 'lib/net/dnd/session.rb', line 22

def initialize(host)
  @connection = Connection.new(host)
  raise ConnectionError, connection.error unless connection.open?
end

Instance Attribute Details

#connection ⇒ Object (readonly)

Returns the value of attribute connection.



17
18
19
 
# File 'lib/net/dnd/session.rb', line 17

def connection
  @connection
end

#fields ⇒ Object (readonly)

Returns the value of attribute fields.



17
18
19
 
# File 'lib/net/dnd/session.rb', line 17

def fields
  @fields
end

Class Method Details

.start(host, field_list = []) ⇒ Object

Starts a new DND session/connection. Called by the module-level start methods.



29
30
31
32
33
 
# File 'lib/net/dnd/session.rb', line 29

def self.start(host, field_list=[])
  session = Session.new(host)
  session.set_fields(field_list)
  session
end

Instance Method Details

#close ⇒ Object

The manual session close command. You only call this method if you aren’t using the block version of the module ‘start’ command. If you use the block, it will automatically close the session when the block exits.



97
98
99
 
# File 'lib/net/dnd/session.rb', line 97

def close
  request(:quit, nil)
end

#find(look_for, one = nil) ⇒ Object

The find command is the real reason for the Net::DND libray. It provides the ability to send a ‘user specifier’ to a connected DND server and then parse the returned data into one or more Net::DND::Profile objects.

You can send the find command in two flavors: the first, when you simply submit the look_for argument will assume that you’re expecting more than one user to match the look_for string. Thus it will always return a array as its result. This array will contain zero, one or more Profile objects.

In it’s second flavor, you are submitting a value for the ‘one’ argument. Normally, this means you’ve sent a :one as the second argument to the call, but any non-false value will work. When called in this manner, you’re telling the Session that you only want a Profile object if your ‘look_for’ returns a single match, otherwise the find will return nil. This flavor is recommended when you are performing a find using a ‘uid’ or a ‘dctsnum’ value.



83
84
85
86
87
88
89
90
91
 
# File 'lib/net/dnd/session.rb', line 83

def find(look_for, one=nil)
  response = request(:lookup, look_for.to_s, fields)
  if one
    return nil unless response.items.length == 1
    Profile.new(fields, response.items[0])
  else
    response.items.map { |item| Profile.new(fields, item) }
  end
end

#open? ⇒ Boolean

Are we still open?

Returns:

  • (Boolean) 


37
38
39
 
# File 'lib/net/dnd/session.rb', line 37

def open?
  connection.open?
end

#set_fields(field_list = []) ⇒ Object

Set the list of fields used by subsequent find commands. These fields are then passed to the Profile.new method when one or more users are returned by the find command. This method will raise a couple of error messages, that you might want to trap for:

FieldNotFound is raised when a specified field is not found in the list of fields known

by the currently connected to DND server.

FieldAccessDenied is raised when a speficied field is one whose value is not world

readable, meaning you need to be in an authenticated session to access it.

You can manually send the set_fields command, if you happen to need to change the list of fields returned by your find commands, after you’ve instantiated the session object.

Raises:



54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/net/dnd/session.rb', line 54

def set_fields(field_list=[])
  response = request(:fields, field_list)
  @fields = []
  raise FieldNotFound, response.error unless response.ok?
  response.items.each do |item|
    field = Field.from_field_line(item)
    if field.read_all? # only world readable fields are valid for DND Profiles
      @fields << field.to_sym
    else
      raise FieldAccessDenied, "#{field.to_s} is not world readable." unless field_list.empty?
    end
  end
end