Branch Collections

So far we’ve been searching from a single base DN, but sometimes what you want is located in different branches of the directory.

For example, hosts might be listed under different domainComponents under the base that correspond to subdomains:

irb> dir.filter( :objectClass => 'dcObject' ).scope( :one ).map( :dc )
# => ["sales", "marketing", "admin", "it", "vpn"]

Treequel::BranchCollections can be used to form searches from multiple bases. They can be constructed from one or more Branchsets:

irb> collection = dir.dc(:marketing).branchset, dir.dc(:sales).branchset )
# => #<Treequel::BranchCollection:0x10ef8c0 2 branchsets: ["dc=marketing,dc=acme,dc=com/(objectClass=*)", "dc=sales,dc=acme,dc=com/(objectClass=*)"]>
Creating a collection from explicit Branchsets

or directly from Branches, which will be converted to Branchsets:

irb> collection = dir.dc(:marketing), dir.dc(:sales) )
# => #<Treequel::BranchCollection:0x10c2dfc 2 branchsets: ["dc=marketing,dc=acme,dc=com/(objectClass=*)", "dc=sales,dc=acme,dc=com/(objectClass=*)"]>
Creating BranchCollection based on the results of a search

or via Treequel::Branchset’s #collection method:

irb> collection = dir.scope(:one).filter(:objectClass => 'dcObject', :dc => ['sales', 'marketing']).collection
# => #<Treequel::BranchCollection:0x50b644 2 branchsets: ["dc=marketing,dc=acme,dc=com/(objectClass=*)", "dc=sales,dc=acme,dc=com/(objectClass=*)"]>
A more-convenient way to turn the results returned by a Branchset into a collection.

You can also compose BranchCollections by appending new Branchsets:

irb> coll =
# => #<Treequel::BranchCollection:0x1021420 0 branchsets: []>
irb> coll << dir.dc( :sales )
# => #<Treequel::BranchCollection:0x1021420 1 branchsets: ["dc=sales,dc=acme,dc=com/(objectClass=*)"]>
irb> coll << dir.dc( :marketing )
# => #<Treequel::BranchCollection:0x1021420 2 branchsets: ["dc=sales,dc=acme,dc=com/(objectClass=*)", "dc=marketing,dc=acme,dc=com/(objectClass=*)"]>
Building up a BranchCollection gradually

or by adding one BranchCollection to another:

irb> east_coast = dir.filter( :dc => [:admin, :it] ).collection
# => #<Treequel::BranchCollection:0x594aac 2 branchsets: ["dc=it,dc=acme,dc=com/(objectClass=*)", "dc=admin,dc=acme,dc=com/(objectClass=*)"]>
irb> west_coast = dir.filter( :dc => [:sales, :marketing] ).collection
# => #<Treequel::BranchCollection:0x55d980 2 branchsets: ["dc=marketing,dc=acme,dc=com/(objectClass=*)", "dc=sales,dc=acme,dc=com/(objectClass=*)"]>
irb> national = east_coast + west_coast
# => #<Treequel::BranchCollection:0x554ec0 4 branchsets: ["dc=it,dc=acme,dc=com/(objectClass=*)", "dc=admin,dc=acme,dc=com/(objectClass=*)", "dc=marketing,dc=acme,dc=com/(objectClass=*)", "dc=sales,dc=acme,dc=com/(objectClass=*)"]>
Combining two BranchCollections into one

BranchCollections work via delegation to their Branchsets, so all of the mutator methods on Branchset are supported by BranchCollection. This means that you can chain collections and filters together, with collections serving as the base for further finer-grained searches:

dir.filter( :ou => 'hosts' ).collection.filter( :cn => 'www' )
Find all hosts named 'www' under all @ou=hosts@ branches