From d4c5e9fdacdc1067d521404947ac02ea8d17e87e Mon Sep 17 00:00:00 2001 From: Oliver Gorwits Date: Mon, 6 Feb 2012 16:01:30 +0000 Subject: [PATCH] add POD for Node and NodeIp --- Netdisco/lib/Netdisco/DB/Result/Node.pm | 70 +++++++++- Netdisco/lib/Netdisco/DB/Result/NodeIp.pm | 131 ++++++++++++++++++- Netdisco/lib/Netdisco/DB/ResultSet/NodeIp.pm | 11 ++ 3 files changed, 209 insertions(+), 3 deletions(-) diff --git a/Netdisco/lib/Netdisco/DB/Result/Node.pm b/Netdisco/lib/Netdisco/DB/Result/Node.pm index 118c8c09..4c7bae03 100644 --- a/Netdisco/lib/Netdisco/DB/Result/Node.pm +++ b/Netdisco/lib/Netdisco/DB/Result/Node.pm @@ -48,22 +48,88 @@ __PACKAGE__->set_primary_key("mac", "switch", "port"); # Created by DBIx::Class::Schema::Loader v0.07015 @ 2012-01-07 14:20:02 # DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:sGGyKEfUkoIFVtmj1wnH7A +=head1 RELATIONSHIPS + +=head2 device + +Returns the single C to which this Node entry was associated at the +time of discovery. + +The JOIN is of type LEFT, in case the C is no longer present in the +database but the relation is being used in C. + +=cut + __PACKAGE__->belongs_to( device => 'Netdisco::DB::Result::Device', { 'foreign.ip' => 'self.switch' }, { join_type => 'LEFT' } ); +=head2 device_port + +Returns the single C to which this Node entry was associated at +the time of discovery. + +The JOIN is of type LEFT, in case the C is no longer present in the +database but the relation is being used in C. + +=cut + # device port may have been deleted (reconfigured modules?) but node remains __PACKAGE__->belongs_to( device_port => 'Netdisco::DB::Result::DevicePort', { 'foreign.ip' => 'self.switch', 'foreign.port' => 'self.port' }, { join_type => 'LEFT' } ); +=head2 ips + +Returns the set of C entries associated with this Node. That is, the +IP addresses which this MAC address was hosting at the time of discovery. + +Note that the Active status of the returned IP entries will all be the same as +the current Node's. + +=cut + __PACKAGE__->has_many( ips => 'Netdisco::DB::Result::NodeIp', { 'foreign.mac' => 'self.mac', 'foreign.active' => 'self.active' } ); -__PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui', 'oui' ); +=head2 oui + +Returns the C table entry matching this Node. You can then join on this +relation and retrieve the Company name from the related table. + +The JOIN is of type LEFT, in case the OUI table has not been populated. + +=cut + +__PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui', 'oui', + { join_type => 'LEFT' } ); + +=head1 ADDITIONAL COLUMNS + +=head2 time_first_stamp + +Formatted version of the C field, accurate to the minute. + +The format is somewhat like ISO 8601 or RFC3339 but without the middle C +between the date stamp and time stamp. That is: + + 2012-02-06 12:49 + +=cut -# accessors for custom formatted columns sub time_first_stamp { return (shift)->get_column('time_first_stamp') } + +=head2 time_last_stamp + +Formatted version of the C field, accurate to the minute. + +The format is somewhat like ISO 8601 or RFC3339 but without the middle C +between the date stamp and time stamp. That is: + + 2012-02-06 12:49 + +=cut + sub time_last_stamp { return (shift)->get_column('time_last_stamp') } 1; diff --git a/Netdisco/lib/Netdisco/DB/Result/NodeIp.pm b/Netdisco/lib/Netdisco/DB/Result/NodeIp.pm index ccfb65d8..05e8b84e 100644 --- a/Netdisco/lib/Netdisco/DB/Result/NodeIp.pm +++ b/Netdisco/lib/Netdisco/DB/Result/NodeIp.pm @@ -37,6 +37,18 @@ __PACKAGE__->set_primary_key("mac", "ip"); # Created by DBIx::Class::Schema::Loader v0.07015 @ 2012-01-07 14:20:02 # DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:9+CuvuVWH88WxAf6IBij8g +=head1 GENERAL NOTES + +This Result Class for the C table supports sites that have customized +their table to include a C column, containing a cached DNS record for the +Node at the time of discovery. + +Calling the C accessor will either return the content of that field if +the field is configured and installed, or else perform a live DNS lookup on +the IP field within the record (returning the first PTR, or undef). + +=cut + # XXX uncomment the following two lines if you have a "dns" column XXX # XXX in your node_ip table which caches the host's name XXX #__PACKAGE__->add_column("dns" => @@ -61,6 +73,17 @@ sub dns { return undef; } +=head1 RELATIONSHIPS + +=head2 oui + +Returns the C table entry matching this Node. You can then join on this +relation and retrieve the Company name from the related table. + +The JOIN is of type LEFT, in case the OUI table has not been populated. + +=cut + __PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui', sub { my $args = shift; @@ -72,8 +95,38 @@ __PACKAGE__->belongs_to( oui => 'Netdisco::DB::Result::Oui', { join_type => 'LEFT' } ); +=head2 node_ips + +Returns the set of all C entries which are associated together with +this IP. That is, all the IP addresses hosted on the same interface (MAC +address) as the current Node IP entry. + +Note that the set will include the original Node IP object itself. If you wish +to find the I IPs excluding this one, see the C helper +routine, below. + +Remember you can pass a filter to this method to find only active or inactive +nodes, but do take into account that both the C and C tables +include independent C fields. + +=cut + __PACKAGE__->has_many( node_ips => 'Netdisco::DB::Result::NodeIp', { 'foreign.mac' => 'self.mac' } ); + +=head2 nodes + +Returns the set of C entries associated with this IP. That is, all the +MAC addresses recorded which have ever hosted this IP Address. + +Remember you can pass a filter to this method to find only active or inactive +nodes, but do take into account that both the C and C tables +include independent C fields. + +See also the C helper routine, below. + +=cut + __PACKAGE__->has_many( nodes => 'Netdisco::DB::Result::Node', { 'foreign.mac' => 'self.mac' } ); @@ -86,6 +139,30 @@ my $search_attr = { '+as' => [qw/ time_first_stamp time_last_stamp /], }; +=head2 ip_aliases( \%cond, \%attrs? ) + +Returns the set of other C entries hosted on the same interface (MAC +address) as the current Node IP, excluding the current IP itself. + +Remember you can pass a filter to this method to find only active or inactive +nodes, but do take into account that both the C and C tables +include independent C fields. + +=over 4 + +=item * + +Results are ordered by time last seen. + +=item * + +Additional columns C and C provide +preformatted timestamps of the C and C fields. + +=back + +=cut + sub ip_aliases { my ($row, $cond, $attrs) = @_; $cond ||= {}; @@ -100,6 +177,34 @@ sub ip_aliases { ->search($cond, $attrs); } +=head2 node_sightings( \%cond, \%attrs? ) + +Returns the set of C entries associated with this IP. That is, all the +MAC addresses recorded which have ever hosted this IP Address. + +Remember you can pass a filter to this method to find only active or inactive +nodes, but do take into account that both the C and C tables +include independent C fields. + +=over 4 + +=item * + +Results are ordered by time last seen. + +=item * + +Additional columns C and C provide +preformatted timestamps of the C and C fields. + +=item * + +A JOIN is performed on the Device table and the Device DNS column prefetched. + +=back + +=cut + sub node_sightings { my ($row, $cond, $attrs) = @_; $cond ||= {}; @@ -114,8 +219,32 @@ sub node_sightings { ->search($cond, $attrs); } -# accessors for custom formatted columns +=head1 ADDITIONAL COLUMNS + +=head2 time_first_stamp + +Formatted version of the C field, accurate to the minute. + +The format is somewhat like ISO 8601 or RFC3339 but without the middle C +between the date stamp and time stamp. That is: + + 2012-02-06 12:49 + +=cut + sub time_first_stamp { return (shift)->get_column('time_first_stamp') } + +=head2 time_last_stamp + +Formatted version of the C field, accurate to the minute. + +The format is somewhat like ISO 8601 or RFC3339 but without the middle C +between the date stamp and time stamp. That is: + + 2012-02-06 12:49 + +=cut + sub time_last_stamp { return (shift)->get_column('time_last_stamp') } 1; diff --git a/Netdisco/lib/Netdisco/DB/ResultSet/NodeIp.pm b/Netdisco/lib/Netdisco/DB/ResultSet/NodeIp.pm index 7721a2f0..02336a42 100644 --- a/Netdisco/lib/Netdisco/DB/ResultSet/NodeIp.pm +++ b/Netdisco/lib/Netdisco/DB/ResultSet/NodeIp.pm @@ -6,6 +6,17 @@ use warnings FATAL => 'all'; # some customize their node_ip table to have a dns column which # is the cached record at the time of discovery + +=head1 has_dns_col + +Some sites customize their C table to include a C field which is +the cached record at the time of node discovery. + +This method returns True if the C table is configured with a C +column. + +=cut + sub has_dns_col { my $set = shift; return $set->result_source->has_column('dns');