class Treequel::BranchCollection

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

new( *branchsets ) click to toggle source

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

&( other_collection ) click to toggle source

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

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

+( other_object ) click to toggle source

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

-( other_object ) click to toggle source

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 192
def -( other_object )
        other_dn = other_object.dn
        return self.reject {|branch| branch.dn == other_dn }
end

<<( object ) click to toggle source

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 165
def <<( object )
        if object.respond_to?( :branchset )
                self.branchsets << object.branchset
        else
                self.branchsets << object
        end

        return self
end

base_dns() click to toggle source

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

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

branchsets() click to toggle source

Delegators that some methods through the collection directly

# File lib/treequel/branchcollection.rb, line 95
def_method_delegators :branchsets, :include?

each( &block ) click to toggle source

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

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

empty?() click to toggle source

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

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

filter() click to toggle source

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

# File lib/treequel/branchcollection.rb, line 89
def_cloning_delegators :filter, :scope, :select, :select_all, :select_more, :timeout,
        :without_timeout

first() click to toggle source

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

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

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

        return branch
end

inspect() click to toggle source

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

# File lib/treequel/branchcollection.rb, line 110
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

map( attribute=nil, &block ) click to toggle source

Overridden to support Treequel::Branchset#map

# File lib/treequel/branchcollection.rb, line 149
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

|( other_collection ) click to toggle source

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

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