[Rt-commit] rt branch, 4.2/importer-docs, created. rt-4.2.12-160-g0f7138a

Shawn Moore shawn at bestpractical.com
Fri Jul 15 18:19:07 EDT 2016


The branch, 4.2/importer-docs has been created
        at  0f7138a3a9145bd3f8aa42f41fbaf0755488bbe9 (commit)

- Log -----------------------------------------------------------------
commit 7c800b40f5dc75e518a135c1e30cd604fb61d5a9
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Mon Sep 22 12:14:20 2014 -0400

    Initial importer docs

diff --git a/lib/RT/Migrate/Importer.pm b/lib/RT/Migrate/Importer.pm
index 5c25d9a..a41f98b 100644
--- a/lib/RT/Migrate/Importer.pm
+++ b/lib/RT/Migrate/Importer.pm
@@ -55,6 +55,20 @@ use Storable qw//;
 use File::Spec;
 use Carp qw/carp/;
 
+=head1 NAME
+
+RT::Migrate::Importer - 
+
+=head1 SYNOPSIS
+
+
+
+=head1 DESCRIPTION
+
+
+
+=cut
+
 sub new {
     my $class = shift;
     my $self = bless {}, $class;
@@ -107,6 +121,10 @@ sub Init {
     $self->{NewCFs} = [];
 }
 
+sub Import {
+    die "Abstract base class; use RT::Migrate::Importer::File";
+}
+
 sub Metadata {
     my $self = shift;
     return $self->{Metadata};
@@ -160,6 +178,15 @@ sub InitStream {
     }
 }
 
+=head2 Resolve C<UID>, C<CLASS>, C<ID>
+
+Called when an object has been successfully created in the database, and
+thus the C<UID> has been locally resolved to the given C<CLASS> and
+C<ID>.  Calling this automatically triggers any pending column updates
+that were waiting on the C<UID> to be completely resolved.
+
+=cut
+
 sub Resolve {
     my $self = shift;
     my ($uid, $class, $id) = @_;
@@ -189,6 +216,13 @@ sub Resolve {
     delete $self->{Pending}{$uid};
 }
 
+=head2 Lookup C<UID>
+
+Returns an array reference of C<[ CLASS, ID ]> if the C<UID> has been
+resolved, or undefined if it has been to be created locally.
+
+=cut
+
 sub Lookup {
     my $self = shift;
     my ($uid) = @_;
@@ -199,6 +233,13 @@ sub Lookup {
     return $self->{UIDs}{$uid};
 }
 
+=head2 LookupObj C<UID>
+
+Returns an object if the C<UID> has been resolved locally, or undefined
+if it has not been.
+
+=cut
+
 sub LookupObj {
     my $self = shift;
     my ($uid) = @_;
@@ -211,6 +252,36 @@ sub LookupObj {
     return $obj;
 }
 
+=head2 Postpone
+
+Takes the following arguments:
+
+=over
+
+=item C<for>
+
+This should be a UID which is not yet resolved.  When this UID is
+resolved locally, its information will be used.
+
+=item C<uid>
+
+When the C<for> UID is resolved, the object with this UID (which must be
+resolved prior to the C<Postpone> call) will be updated using
+information from C<for>.
+
+=item C<column>, C<classcolumn>, or C<uri>
+
+One or more of these must be specified, and determine how the C<uid>
+object is updated with the C<for> object's information.  The C<uid>
+object's C<column> will be set to the C<for> object's id.  The C<uid>
+object's column named C<classcolumn> will be set to the C<for> object's
+class.  The C<uid> object's column named C<uri> will be set to the
+internal URI of the C<for> object.
+
+=back
+
+=cut
+
 sub Postpone {
     my $self = shift;
     my %args = (
@@ -224,6 +295,10 @@ sub Postpone {
     my $uid = delete $args{for};
 
     if (defined $uid) {
+        warn "The 'for' argument to Postpone ($uid) should still be unresolved!"
+            if $self->Lookup($uid);
+        warn "The 'uid' argument to Postpone ($args{uid}) should already be resolved!"
+            unless $self->Lookup($args{uid});
         push @{$self->{Pending}{$uid}}, \%args;
     } else {
         push @{$self->{Invalid}}, \%args;
@@ -465,11 +540,25 @@ sub Invalid {
                      : $self->{Invalid};
 }
 
+=head2 Organization
+
+Returns the organization the serialized data was read 
+
+=cut
+
 sub Organization {
     my $self = shift;
     return $self->{Organization};
 }
 
+=head2 Progress [C<SUBREF>]
+
+Gets or sets the progress callback; this will be called with each object
+as it is finished being imported, or with undef (and a second value of
+C<force>) when the stream is finally closed.
+
+=cut
+
 sub Progress {
     my $self = shift;
     return defined $self->{Progress} unless @_;

commit 0f7138a3a9145bd3f8aa42f41fbaf0755488bbe9
Author: Shawn M Moore <shawn at bestpractical.com>
Date:   Fri Jul 15 18:18:50 2016 -0400

    Finish method docs and comments for RT::Migrate::Importer

diff --git a/lib/RT/Migrate/Importer.pm b/lib/RT/Migrate/Importer.pm
index a41f98b..e078f39 100644
--- a/lib/RT/Migrate/Importer.pm
+++ b/lib/RT/Migrate/Importer.pm
@@ -125,11 +125,25 @@ sub Import {
     die "Abstract base class; use RT::Migrate::Importer::File";
 }
 
+=head2 Metadata
+
+Returns metadata (e.g. C<Organization>, C<Clone>, C<Incremental>) about the import
+stream as a hash reference.
+
+=cut
+
 sub Metadata {
     my $self = shift;
     return $self->{Metadata};
 }
 
+=head2 LoadMetadata C<DATA>
+
+Reads important metadata from the import stream from C<DATA> and validates
+that its version is compatible. See L</Metadata>.
+
+=cut
+
 sub LoadMetadata {
     my $self = shift;
     my ($data) = @_;
@@ -146,6 +160,12 @@ sub LoadMetadata {
     $self->{Files}        = $data->{Files} if $data->{Final};
 }
 
+=head2 InitStream
+
+Sets up the initial state to begin importing data.
+
+=cut
+
 sub InitStream {
     my $self = shift;
 
@@ -219,7 +239,7 @@ sub Resolve {
 =head2 Lookup C<UID>
 
 Returns an array reference of C<[ CLASS, ID ]> if the C<UID> has been
-resolved, or undefined if it has been to be created locally.
+resolved, or undefined if it has not yet been created locally.
 
 =cut
 
@@ -269,14 +289,22 @@ When the C<for> UID is resolved, the object with this UID (which must be
 resolved prior to the C<Postpone> call) will be updated using
 information from C<for>.
 
-=item C<column>, C<classcolumn>, or C<uri>
+=item C<column>, C<classcolumn>, C<uri>, or C<method>
+
+One or more of these must be specified, and determine how the C<uid> object is
+updated with the C<for> object's information.
 
-One or more of these must be specified, and determine how the C<uid>
-object is updated with the C<for> object's information.  The C<uid>
-object's C<column> will be set to the C<for> object's id.  The C<uid>
-object's column named C<classcolumn> will be set to the C<for> object's
-class.  The C<uid> object's column named C<uri> will be set to the
-internal URI of the C<for> object.
+The C<uid> object's C<column> will be set to the C<for> object's id.
+
+The C<uid> object's column named C<classcolumn> will be set to the C<for>
+object's class.
+
+The C<uid> object's column named C<uri> will be set to the internal URI of the
+C<for> object.
+
+The method named by C<method> will be called on the C<uid> object, passing
+parameters for this importer instance, the hashref of arguments passed to
+L</Postpone>, the C<for> object's class, and the C<for> object's id.
 
 =back
 
@@ -305,6 +333,16 @@ sub Postpone {
     }
 }
 
+=head2 SkipTransactions C<UID>
+
+Flags this C<UID> such that transactions on this record should not be
+imported. This is typically used for duplicate records (e.g. users, groups,
+L<RT::System>) since we use the original record.
+
+This has no effect for clones, as we want a pristine copy.
+
+=cut
+
 sub SkipTransactions {
     my $self = shift;
     my ($uid) = @_;
@@ -312,12 +350,26 @@ sub SkipTransactions {
     $self->{SkipTransactions}{$uid} = 1;
 }
 
+=head2 ShouldSkipTransaction C<UID>
+
+Returns a boolean indicating whether L</SkipTransactions> has been invoked for
+this C<UID>.
+
+=cut
+
 sub ShouldSkipTransaction {
     my $self = shift;
     my ($uid) = @_;
     return exists $self->{SkipTransactions}{$uid};
 }
 
+=head2 MergeValues C<OBJECT>, C<DATA>
+
+Updates each unset column in C<OBJECT> with each value in C<DATA>. Any
+references will be resolved, if needed, using L</Postpone>.
+
+=cut
+
 sub MergeValues {
     my $self = shift;
     my ($obj, $data) = @_;
@@ -343,6 +395,15 @@ sub MergeValues {
     }
 }
 
+=head2 SkipBy C<COLUMN>, C<CLASS>, C<UID>, C<DATA>
+
+This is used to skip records that already exist. If there is an instance of
+C<CLASS> whose value for C<COLUMN> is the same as what is in C<DATA>, then
+the existing record is used instead of the record being imported. No values
+are merged into the existing record; for that, see L</MergeBy>.
+
+=cut
+
 sub SkipBy {
     my $self = shift;
     my ($column, $class, $uid, $data) = @_;
@@ -357,6 +418,15 @@ sub SkipBy {
     return $obj;
 }
 
+=head2 MergeBy C<COLUMN>, C<CLASS>, C<UID>, C<DATA>
+
+This is used to skip records that already exist. If there is an instance of
+C<CLASS> whose value for C<COLUMN> is the same as what is in C<DATA>, then
+the existing record is used instead of the record being imported. Values
+from C<DATA> are merged into the existing record.
+
+=cut
+
 sub MergeBy {
     my $self = shift;
     my ($column, $class, $uid, $data) = @_;
@@ -367,6 +437,18 @@ sub MergeBy {
     return 1;
 }
 
+=head2 Qualify C<NAME>
+
+Returns the passed-in name with the organization and a colon prepended, if
+needed. The name is instead returned as-is for clones, imports without an
+organization, imports with C<--exclude-organization>, or imports where the
+organization is the same as the current RT.
+
+This is meant to disambiguate records (e.g. queues) that would otherwise
+violate uniqueness constraints.
+
+=cut
+
 sub Qualify {
     my $self = shift;
     my ($string) = @_;
@@ -377,6 +459,15 @@ sub Qualify {
     return $self->{Organization}.": $string";
 }
 
+=head2 Create C<CLASS>, C<UID>, C<DATA>
+
+Creates a record of class C<CLASS> for identifier C<UID> using the provided
+C<DATA>. This will invoke the record's PreInflate and PostInflate for
+massaging data before and after creation. As part of this process,
+L</Resolve> will be invoked to finalize the class and id for this C<UID>.
+
+=cut
+
 sub Create {
     my $self = shift;
     my ($class, $uid, $data) = @_;
@@ -419,10 +510,19 @@ sub Create {
     return $obj;
 }
 
+=head2 ReadStream C<FH>
+
+Takes a L<Storable>-encoded stream and imports the
+L<RT::Migrate::Serializer>-generated records from it.
+
+=cut
+
 sub ReadStream {
     my $self = shift;
     my ($fh) = @_;
 
+    # simplify the ticket load process to avoid loading the wrong ticket due
+    # to merges
     no warnings 'redefine';
     local *RT::Ticket::Load = sub {
         my $self = shift;
@@ -440,6 +540,7 @@ sub ReadStream {
         return;
     }
 
+    # Data files are stored as arrayrefs
     my ($class, $uid, $data) = @{$loaded};
 
     if ($self->{Incremental}) {
@@ -504,6 +605,13 @@ sub ReadStream {
     $self->{Progress}->($obj) if $self->{Progress};
 }
 
+=head2 CloseStream
+
+Finalizes this import; serves to update imported CFs that were global to
+instead be applied only to the newly-imported queues.
+
+=cut
+
 sub CloseStream {
     my $self = shift;
 
@@ -522,18 +630,38 @@ sub CloseStream {
     $self->{NewCFs} = [];
 }
 
+=head2 ObjectCount
+
+Returns a hash mapping each class to the number of imported objects of that
+class. This may be called midstream to see how much progress has been made.
+
+=cut
 
 sub ObjectCount {
     my $self = shift;
     return %{ $self->{ObjectCount} };
 }
 
+=head2 Missing
+
+Returns the list of not-yet imported UIDs which are required for other
+objects using L</Postpone>.
+
+=cut
+
 sub Missing {
     my $self = shift;
     return wantarray ? sort keys %{ $self->{Pending} }
         : keys %{ $self->{Pending} };
 }
 
+=head2 Invalid
+
+Returns the list of objects missing from the source database before
+serialization.
+
+=cut
+
 sub Invalid {
     my $self = shift;
     return wantarray ? sort { $a->{uid} cmp $b->{uid} } @{ $self->{Invalid} }
@@ -542,7 +670,7 @@ sub Invalid {
 
 =head2 Organization
 
-Returns the organization the serialized data was read 
+Returns the organization from the RT which generated the serialized data.
 
 =cut
 

-----------------------------------------------------------------------


More information about the rt-commit mailing list