[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