Class: Blather::JID

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/blather/jid.rb

Overview

Jabber ID or JID

See [RFC 3920 Section 3 - Addressing](xmpp.org/rfcs/rfc3920.html#addressing)

An entity is anything that can be considered a network endpoint (i.e., an ID on the network) and that can communicate using XMPP. All such entities are uniquely addressable in a form that is consistent with RFC 2396 [URI]. For historical reasons, the address of an XMPP entity is called a Jabber Identifier or JID. A valid JID contains a set of ordered elements formed of a domain identifier, node identifier, and resource identifier.

The syntax for a JID is defined below using the Augmented Backus-Naur Form as defined in [ABNF]. (The IPv4address and IPv6address rules are defined in Appendix B of [IPv6]; the allowable character sequences that conform to the node rule are defined by the Nodeprep profile of [STRINGPREP] as documented in Appendix A of this memo; the allowable character sequences that conform to the resource rule are defined by the Resourceprep profile of [STRINGPREP] as documented in Appendix B of this memo; and the sub-domain rule makes reference to the concept of an internationalized domain label as described in [IDNA].)

jid             = [ node "@" ] domain [ "/" resource ]
domain          = fqdn / address-literal
fqdn            = (sub-domain 1*("." sub-domain))
sub-domain      = (internationalized domain label)
address-literal = IPv4address / IPv6address

All JIDs are based on the foregoing structure. The most common use of this structure is to identify an instant messaging user, the server to which the user connects, and the user's connected resource (e.g., a specific client) in the form of <user@host/resource>. However, node types other than clients are possible; for example, a specific chat room offered by a multi-user chat service could be addressed as <room@service> (where "room" is the name of the chat room and "service" is the hostname of the multi-user chat service) and a specific occupant of such a room could be addressed as <room@service/nick> (where "nick" is the occupant's room nickname). Many other JID types are possible (e.g., <domain/resource> could be a server-side script or service).

Each allowable portion of a JID (node identifier, domain identifier, and resource identifier) MUST NOT be more than 1023 bytes in length, resulting in a maximum total size (including the '@' and '/' separators) of 3071 bytes.

Constant Summary

PATTERN =

Validating pattern for JID string

/^(?:([^@]*)@)??([^@\/]*)(?:\/(.*?))?$/.freeze

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Blather::JID) initialize(jid) - (Blather::JID) initialize(jid) - (Blather::JID) initialize(node, domain = nil, resource = nil)

Create a new JID object

Overloads:

  • - (Blather::JID) initialize(jid)

    Passes the jid object right back out

  • - (Blather::JID) initialize(jid)

    Creates a new JID parsed out of the provided jid ("node@domain/resource")

  • - (Blather::JID) initialize(node, domain = nil, resource = nil)

    Creates a new JID

Raises:

  • (ArgumentError)

    if the parts of the JID are too large (1023 bytes)



77
78
79
80
81
82
83
84
85
86
87
88
89
# File 'lib/blather/jid.rb', line 77

def initialize(node, domain = nil, resource = nil)
  @resource = resource
  @domain = domain
  @node = node

  if @domain.nil? && @resource.nil?
    @node, @domain, @resource = @node.to_s.scan(PATTERN).first
  end

  raise ArgumentError, 'Node too long' if (@node || '').length > 1023
  raise ArgumentError, 'Domain too long' if (@domain || '').length > 1023
  raise ArgumentError, 'Resource too long' if (@resource || '').length > 1023
end

Instance Attribute Details

- (Object) domain (readonly)

Returns the value of attribute domain



52
53
54
# File 'lib/blather/jid.rb', line 52

def domain
  @domain
end

- (Object) node (readonly)

Returns the value of attribute node



52
53
54
# File 'lib/blather/jid.rb', line 52

def node
  @node
end

- (Object) resource (readonly)

Returns the value of attribute resource



52
53
54
# File 'lib/blather/jid.rb', line 52

def resource
  @resource
end

Class Method Details

+ (Object) new(node, domain = nil, resource = nil)



57
58
59
# File 'lib/blather/jid.rb', line 57

def self.new(node, domain = nil, resource = nil)
  node.is_a?(JID) ? node : super
end

Instance Method Details

- (Fixnum<-1, 0, 1>) <=>(other)

Compare two JIDs, helpful for sorting etc.

String representations are compared, see JID#to_s



128
129
130
# File 'lib/blather/jid.rb', line 128

def <=>(other)
  to_s.downcase <=> other.to_s.downcase
end

- (Blather::JID) strip!

Removes the resource (sets it to nil)



117
118
119
120
# File 'lib/blather/jid.rb', line 117

def strip!
  @resource = nil
  self
end

- (Blather::JID) stripped

Returns a new JID with resource removed.



110
111
112
# File 'lib/blather/jid.rb', line 110

def stripped
  dup.strip!
end

- (true, false) stripped?

Test if JID is stripped



136
137
138
# File 'lib/blather/jid.rb', line 136

def stripped?
  @resource.nil?
end

- (String) to_s

Turn the JID into a string

  • ""

  • "domain"

  • "node@domain"

  • "domain/resource"

  • "node@domain/resource"



100
101
102
103
104
105
# File 'lib/blather/jid.rb', line 100

def to_s
  s = @domain
  s = "#{@node}@#{s}" if @node
  s = "#{s}/#{@resource}" if @resource
  s
end