BranchCollection

class
Superclass
Object
Included Modules
Enumerable
Treequel::Constants
Extended With
Loggability
Treequel::Delegation

A Treequel::BranchCollection is a union of Treequel::Branchset objects, suitable for performing operations on multiple branches of the directory at once.

For example, if you have hosts under ou=Hosts in two different subdomains (e.g., acme.com, seattle.acme.com, and newyork.acme.com), and you want to search for a host by its CN, you could do so like this:

# Top-level hosts, and those in the 'seattle' subdomain, but not # those in the 'newyork' subdomain: west_coast_hosts = dir.ou( :hosts ) + dir.dc( :seattle ).ou( :hosts ) west_coast_www_hosts = west_coast_hosts.filter( :cn => 'www' )

# And one that includes hosts in all three DCs: all_hosts = west_coast_hosts + dir.dc( :newyork ).ou( :hosts ) all_ns_hosts = all_hosts.filter( :cn => 'ns*' )

Note that you could accomplish most of what BranchCollection does using filters, but some people might find this a bit more readable.

Public Class Methods

anchor
new( *branchsets )

Create a new Treequel::BranchCollection that will operate on the given branchsets, which can be either Treequel::Branchset or Treequel::Branch objects.

# File lib/treequel/branchcollection.rb, line 80
def initialize( *branchsets )
        @branchsets = branchsets.flatten.collect do |obj|
                if obj.respond_to?( :each )
                        obj
                else
                        Treequel::Branchset.new( obj )
                end
        end
end

Public Instance Methods

anchor
&( other_collection )

Return a new Treequel::BranchCollection that contains the union of the branchsets from both collections.

# File lib/treequel/branchcollection.rb, line 206
def &( other_collection )
        return self.class.new( self.branchsets & other_collection.branchsets )
end
anchor
+( other_object )

Return either a new Treequel::BranchCollection that includes both the receiver's Branchsets and those in other_object (if it responds_to branchsets), or the results from executing the BranchCollection's search with other_object appended if it doesn't.

# File lib/treequel/branchcollection.rb, line 185
def +( other_object )
        if other_object.respond_to?( :branchsets )
                return self.class.new( self.branchsets + other_object.branchsets )
        elsif other_object.respond_to?( :collection )
                return self.class.new( self.branchsets + [other_object] )
        else
                return self.all + Array( other_object )
        end
end
anchor
-( other_object )

Return the results from each of the receiver's Branchsets without the other_object, which must respond to dn.

# File lib/treequel/branchcollection.rb, line 198
def -( other_object )
        other_dn = other_object.dn
        return self.reject {|branch| branch.dn == other_dn }
end
anchor
<<( object )

Append operator: add the specified object (either a Treequel::Branchset or an object that responds to branchset and returns a Treequel::Branchset) to the collection and return the receiver.

# File lib/treequel/branchcollection.rb, line 171
def <<( object )
        if object.respond_to?( :branchset )
                self.branchsets << object.branchset
        else
                self.branchsets << object
        end

        return self
end
anchor
base_dns()

Return the base DN of all of the collection's Branchsets.

# File lib/treequel/branchcollection.rb, line 219
def base_dns
        return self.branchsets.collect {|bs| bs.base_dn }
end
anchor
branchsets()

Delegators that some methods through the collection directly

# File lib/treequel/branchcollection.rb, line 101
def_method_delegators :branchsets, :include?
anchor
each( &block )

Iterate over the Treequel::Branches found by each member branchset, yielding each one in turn.

# File lib/treequel/branchcollection.rb, line 128
def each( &block )
        raise LocalJumpError, "no block given" unless block
        self.branchsets.each do |bs|
                bs.each( &block )
        end
end
anchor
empty?()

Return true if none of the collection's branches match any entries.

# File lib/treequel/branchcollection.rb, line 149
def empty?
        return self.branchsets.all? {|bs| bs.empty? } ? true : false
end
anchor
filter()

Delegator methods that clone the receiver with the results of mapping the branchsets with the delegated method.

# File lib/treequel/branchcollection.rb, line 95
def_cloning_delegators :filter, :scope, :select, :select_all, :select_more, :timeout,
        :without_timeout
anchor
first()

Return the first Treequel::Branch that is returned from the collection's branchsets.

# File lib/treequel/branchcollection.rb, line 137
def first
        branch = nil

        self.branchsets.each do |bs|
                break if branch = bs.first
        end

        return branch
end
anchor
inspect()

Return a human-readable string representation of the object suitable for debugging.

# File lib/treequel/branchcollection.rb, line 116
def inspect
        "#<%s:0x%0x %d branchsets: %p>" % [
                self.class.name,
                self.object_id * 2,
                self.branchsets.length,
                self.branchsets.collect {|bs| bs.to_s },
        ]
end
anchor
map( attribute=nil, &block )

Overridden to support Branchset#map

# File lib/treequel/branchcollection.rb, line 155
def map( attribute=nil, &block )
        if attribute
                if block
                        super() {|branch| block.call(branch[attribute]) }
                else
                        super() {|branch| branch[attribute] }
                end
        else
                super( &block )
        end
end
anchor
|( other_collection )

Return a new Treequel::BranchCollection that contains the intersection of the branchsets from both collections.

# File lib/treequel/branchcollection.rb, line 213
def |( other_collection )
        return self.class.new( self.branchsets | other_collection.branchsets )
end