Diff of /Sprout/ERDB.pm

-revision 1.94, Thu Dec  6 14:58:03 2007 UTC
+revision 1.103, Tue Sep 16 18:57:59 2008 UTC
 Line 11
      use Time::HiRes qw(gettimeofday);
      use Digest::MD5 qw(md5_base64);
      use CGI;
+     use WikiTools;
  =head1 Entity-Relationship Database Package
-Line 389
+Line 390
                                    Entities => 'Entity',
                                    Fields => 'Field',
                                    Indexes => 'Index',
-                                   IndexFields => 'IndexField'
+                                   IndexFields => 'IndexField',
+                                   Issues => 'Issue',
+                                   Shapes => 'Shape'
                                  },
                    KeyAttr =>    { Relationship => 'name',
                                    Entity => 'name',
-                                   Field => 'name'
+                                   Field => 'name',
+                                   Shape => 'name'
                                  },
                    SuppressEmpty => 1,
                   );
  my %XmlInOpts  = (
-                   ForceArray => ['Field', 'Index', 'IndexField', 'Relationship', 'Entity'],
+                   ForceArray => [qw(Field Index IndexField Relationship Entity Shape)],
                    ForceContent => 1,
                    NormalizeSpace => 2,
                   );
-Line 408
+Line 412
                    XMLDecl => 1,
                   );
  =head2 Public Methods
  =head3 new
-Line 433
+Line 436
  sub new {
      # Get the parameters.
-     my ($class, $dbh, $metaFileName, $options) = @_;
+     my ($class, $dbh, $metaFileName, %options) = @_;
      # Load the meta-data.
      my $metaData = _LoadMetaData($metaFileName);
      # Create the object.
-Line 657
+Line 660
      return Data::Dumper::Dumper($self->{_metaData});
  }
+ =head3 GenerateWikiData
+     my @wikiLines = $erdb->GenerateWikiData();
+ Build a description of the database for the wiki. The database will be
+ organized into a single page, with sections for each entity and relationship.
+ The return value is a list of text lines.
+ =cut
+ sub GenerateWikiData {
+     # Get the parameters.
+     my ($self) = @_;
+     # We'll build the wiki text in here.
+     my @retVal = ();
+     # Get the metadata object.
+     my $metadata = $self->{_metaData};
+     # Get the title string. This will become the page name.
+     my $title = $metadata->{Title}->{content};
+     # Get the entity and relationship lists.
+     my $entityList = $metadata->{Entities};
+     my $relationshipList = $metadata->{Relationships};
+     my $shapeList = $metadata->{Shapes};
+     # Start with the introductory text.
+     push @retVal, WikiTools::Heading(2, "Introduction");
+     if (my $notes = $metadata->{Notes}) {
+         push @retVal, WikiNote($notes->{content});
+     }
+     # Generate issue list.
+     if (my $issues = $metadata->{Issues}) {
+         push @retVal, WikiTools::Heading(3, 'Issues');
+         push @retVal, WikiTools::List(map { $_->{content} } @{$issues});
+     }
+     # Start the entity section.
+     push @retVal, WikiTools::Heading(2, "Entities");
+     # Loop through the entities. Note that unlike the situation with HTML, we
+     # don't need to generate the table of contents manually, just the data
+     # itself.
+     for my $key (sort keys %$entityList) {
+         # Create a header for this entity.
+         push @retVal, "", WikiTools::Heading(3, $key);
+         # Get the entity data.
+         my $entityData = $entityList->{$key};
+         # Plant the notes here, if there are any.
+         push @retVal, _ObjectNotes($entityData);
+         # Now we list the entity's relationships (if any). First, we build a list
+         # of the relationships relevant to this entity.
+         my @rels = ();
+         for my $rel (sort keys %$relationshipList) {
+             my $relStructure = $relationshipList->{$rel};
+             if ($relStructure->{from} eq $key || $relStructure->{to} eq $key) {
+                 # Get the relationship sentence.
+                 my $relSentence = _ComputeRelationshipSentence($rel, $relStructure);
+                 # Linkify it.
+                 my $linkedRel = WikiTools::LinkMarkup("#$rel", $rel);
+                 $relSentence =~ s/$rel/$linkedRel/;
+                 push @rels, $relSentence;
+             }
+         }
+         # Add the relationships as a Wiki list.
+         push @retVal, WikiTools::List(@rels);
+         # Get the entity's relations.
+         my $relationList = $entityData->{Relations};
+         # Loop through the relations, displaying them.
+         for my $relation (sort keys %{$relationList}) {
+             my $wikiString = _WikiRelationTable($relation, $relationList->{$relation});
+             push @retVal, $wikiString;
+         }
+     }
+     # Now the entities are documented. Next we do the relationships.
+     push @retVal, WikiTools::Heading(2, "Relationships");
+     for my $key (sort keys %$relationshipList) {
+         my $relationshipData = $relationshipList->{$key};
+         # Create the relationship heading.
+         push @retVal, WikiTools::Heading(3, $key);
+         # Describe the relationship arity. Note there's a bit of trickiness involving recursive
+         # many-to-many relationships. In a normal many-to-many we use two sentences to describe
+         # the arity (one for each direction). This is a bad idea for a recursive relationship,
+         # since both sentences will say the same thing.
+         my $arity = $relationshipData->{arity};
+         my $fromEntity = $relationshipData->{from};
+         my $toEntity = $relationshipData->{to};
+         my @listElements = ();
+         my $boldCode = WikiTools::BoldCode();
+         if ($arity eq "11") {
+             push @listElements, "Each $boldCode$fromEntity$boldCode relates to at most one $boldCode$toEntity$boldCode.";
+         } else {
+             push @listElements, "Each $boldCode$fromEntity$boldCode relates to multiple $boldCode${toEntity}s$boldCode.";
+             if ($arity eq "MM" && $fromEntity ne $toEntity) {
+                 push @listElements, "Each $boldCode$toEntity$boldCode relates to multiple $boldCode${fromEntity}s$boldCode.";
+             }
+         }
+         push @retVal, WikiTools::List(@listElements);
+         # Plant the notes here, if there are any.
+         push @retVal, _ObjectNotes($relationshipData);
+         # Finally, the relationship table.
+         my $wikiString = _WikiRelationTable($key, $relationshipData->{Relations}->{$key});
+         push @retVal, $wikiString;
+     }
+     # Now loop through the miscellaneous shapes.
+     if ($shapeList) {
+         push @retVal, WikiTools::Heading(2, "Miscellaneous");
+         for my $shape (sort keys %$shapeList) {
+             push @retVal, WikiTools::Heading(3, $shape);
+             my $shapeData = $shapeList->{$shape};
+             push @retVal, _ObjectNotes($shapeData);
+         }
+     }
+     # All done. Return the lines.
+     return @retVal;
+ }
  =head3 CreatePPO
      ERDB::CreatePPO($erdbXMLFile, $ppoXMLFile);
-Line 946
+Line 1062
          # Push the result into the field list.
          push @fieldList, $fieldString;
      }
-     # If this is a root table, add the "new_record" flag. It defaults to 0, so
-     if ($rootFlag) {
-         push @fieldList, "new_record $TypeTable{boolean}->{sqlType} NOT NULL DEFAULT 0";
-     }
      # Convert the field list into a comma-delimited string.
      my $fieldThing = join(', ', @fieldList);
      # Insure the table is not already there.
-Line 1416
+Line 1528
      return sort keys %{$entityList};
  }
+ =head3 GetConnectingRelationships
+     my @list = $erdb->GetConnectingRelationships($entityName);
+ Return a list of the relationships connected to the specified entity.
+ =over 4
+ =item entityName
+ Entity whose connected relationships are desired.
+ =item RETURN
+ Returns a list of the relationships that originate from the entity.
+ If the entity is on the from end, it will return the relationship
+ name. If the entity is on the to end it will return the converse of
+ the relationship name.
+ =back
+ =cut
+ sub GetConnectingRelationships {
+     # Get the parameters.
+     my ($self, $entityName) = @_;
+     # Declare the return variable.
+     my @retVal;
+     # Get the relationship list.
+     my $relationships = $self->{_metaData}->{Relationships};
+     # Find the entity.
+     my $entity = $self->{_metaData}->{Entities}->{$entityName};
+     # Only proceed if the entity exists.
+     if (! defined $entity) {
+         Trace("Entity $entityName not found.") if T(3);
+     } else {
+         # Loop through the relationships.
+         my @rels = keys %$relationships;
+         Trace(scalar(@rels) . " relationships found in connection search.") if T(3);
+         for my $relationshipName (@rels) {
+             my $relationship = $relationships->{$relationshipName};
+             if ($relationship->{from} eq $entityName) {
+                 # Here we have a forward relationship.
+                 push @retVal, $relationshipName;
+             } elsif ($relationship->{to} eq $entityName) {
+                 # Here we have a backward relationship. In this case, the
+                 # converse relationship name is preferred if it exists.
+                 my $converse = $relationship->{converse} || $relationshipName;
+                 push @retVal, $converse;
+             }
+         }
+     }
+     # Return the result.
+     return @retVal;
+ }
  =head3 GetDataTypes
      my %types = ERDB::GetDataTypes();
-Line 1999
+Line 2169
          # Loop through the ends of the relationship.
          for my $dir ('from', 'to') {
              if ($structure->{$dir} eq $originEntityName) {
-                 # Delete all relationship instances on this side of the entity instance.
-                 Trace("Disconnecting in $dir direction with ID \"$originEntityID\".");
-                 $dbh->SQL("DELETE FROM $relationshipName WHERE ${dir}_link = ?", 0, $originEntityID);
                  $found = 1;
+                 # Here we want to delete all relationship instances on this side of the
+                 # entity instance.
+                 Trace("Disconnecting in $dir direction with ID \"$originEntityID\".");
+                 # We do this delete in batches to keep it from dragging down the
+                 # server.
+                 my $limitClause = ($FIG_Config::delete_limit ? "LIMIT $FIG_Config::delete_limit" : "");
+                 my $done = 0;
+                 while (! $done) {
+                     # Do the delete.
+                     my $rows = $dbh->SQL("DELETE FROM $relationshipName WHERE ${dir}_link = ? $limitClause", 0, $originEntityID);
+                     # See if we're done. We're done if no rows were found or the delete is unlimited.
+                     $done = ($rows == 0 || ! $limitClause);
+                 }
              }
          }
          # Insure we found the entity on at least one end.
-Line 2190
+Line 2370
      }
      # Now we parse the key names into sort parameters. First, we prime the return
      # string.
-     my $retVal = "sort -t\"\t\" ";
+     my $retVal = "sort -S 1G -T\"$FIG_Config::temp\" -t\"\t\" ";
      # Get the relation's field list.
      my @fields = @{$relationData->{Fields}};
      # Loop through the keys.
-Line 2220
+Line 2400
                  # will stop the inner loop. Note that the field number is
                  # 1-based in the sort command, so we have to increment the
                  # index.
-                 $fieldSpec = ($i + 1) . $modifier;
+                 my $realI = $i + 1;
+                 $fieldSpec = "$realI,$realI$modifier";
              }
          }
          # Add this field to the sort command.
-Line 2611
+Line 2792
                  push @missing, $fieldName;
              }
          }
-         # If we are the primary relation, add the new-record flag.
-         if ($relationName eq $newObjectType) {
-             push @valueList, 1;
-             push @fieldNameList, "new_record";
-         }
          # Only proceed if there are no missing fields.
          if (@missing > 0) {
              Trace("Relation $relationName for $newObjectType skipped due to missing fields: " .
-Line 2723
+Line 2899
  =head3 LoadTable
-     my $results = $erdb->LoadTable($fileName, $relationName, $truncateFlag);
+     my $results = $erdb->LoadTable($fileName, $relationName, %options);
  Load data from a tab-delimited file into a specified table, optionally re-creating the table
  first.
-Line 2738
+Line 2914
  Name of the relation to be loaded. This is the same as the table name.
- =item truncateFlag
+ =item options
- TRUE if the table should be dropped and re-created, else FALSE
+ A hash of load options.
  =item RETURN
-Line 2748
+Line 2924
  =back
+ The permissible options are as follows.
+ =over 4
+ =item truncate
+ If TRUE, then the table will be erased before loading.
+ =item mode
+ Mode in which the load should operate, either C<low_priority> or C<concurrent>.
+ This option is only applicable to a MySQL database.
+ =item partial
+ If TRUE, then it is assumed that this is a partial load, and the table will not
+ be analyzed and compacted at the end.
+ =back
  =cut
  sub LoadTable {
      # Get the parameters.
-     my ($self, $fileName, $relationName, $truncateFlag) = @_;
+     my ($self, $fileName, $relationName, %options) = @_;
      # Create the statistical return object.
      my $retVal = _GetLoadStats();
      # Trace the fact of the load.
-Line 2763
+Line 2959
      # Get the relation data.
      my $relation = $self->_FindRelation($relationName);
      # Check the truncation flag.
-     if ($truncateFlag) {
+     if ($options{truncate}) {
          Trace("Creating table $relationName") if T(2);
          # Compute the row count estimate. We take the size of the load file,
          # divide it by the estimated row size, and then multiply by 2 to
-Line 2789
+Line 2985
      # Load the table.
      my $rv;
      eval {
-         $rv = $dbh->load_table(file => $fileName, tbl => $relationName);
+         $rv = $dbh->load_table(file => $fileName, tbl => $relationName, style => $options{mode});
      };
      if (!defined $rv) {
          $retVal->AddMessage($@) if ($@);
-Line 2800
+Line 2996
          $retVal->Add("tables");
          my $size = -s $fileName;
          Trace("$size bytes loaded into $relationName.") if T(2);
+         $retVal->Add("bytes", $size);
          # If we're rebuilding, we need to create the table indexes.
-         if ($truncateFlag) {
+         if ($options{truncate}) {
              # Indexes are created here for PostGres. For PostGres, indexes are
              # best built at the end. For MySQL, the reverse is true.
              if (! $dbh->{_preIndex}) {
-Line 2822
+Line 3019
          }
      }
      # Analyze the table to improve performance.
+     if (! $options{partial}) {
      Trace("Analyzing and compacting $relationName.") if T(3);
-     $dbh->vacuum_it($relationName);
+         $self->Analyze($relationName);
+     }
      Trace("$relationName load completed.") if T(3);
      # Return the statistics.
      return $retVal;
  }
+ =head3 Analyze
+     $erdb->Analyze($tableName);
+ Analyze and compact a table in the database. This is useful after a load
+ to improve the performance of the indexes.
+ =over 4
+ =item tableName
+ Name of the table to be analyzed and compacted.
+ =back
+ =cut
+ sub Analyze {
+     # Get the parameters.
+     my ($self, $tableName) = @_;
+     # Analyze the table.
+     $self->{_dbh}->vacuum_it($tableName);
+ }
+ =head3 TruncateTable
+     $erdb->TruncateTable($table);
+ Delete all rows from a table quickly. This uses the built-in SQL
+ C<TRUNCATE> statement, which effectively drops and re-creates a table
+ with all its settings intact.
+ =over 4
+ =item table
+ Name of the table to be cleared.
+ =back
+ =cut
+ sub TruncateTable {
+     # Get the parameters.
+     my ($self, $table) = @_;
+     # Get the database handle.
+     my $dbh = $self->{_dbh};
+     # Execute a truncation comment.
+     $dbh->SQL("TRUNCATE TABLE $table");
+ }
  =head3 CreateSearchIndex
      $erdb->CreateSearchIndex($objectName);
-Line 3009
+Line 3260
      my $query = $self->Get([$entityType], "$entityType(id) = ?", [$ID]);
      # Get the first (and only) object.
      my $retVal = $query->Fetch();
+     if (T(3)) {
+         if ($retVal) {
+             Trace("Entity $entityType \"$ID\" found.");
+         } else {
+             Trace("Entity $entityType \"$ID\" not found.");
+         }
+     }
      # Return the result.
      return $retVal;
  }
-Line 3201
+Line 3459
          push @retVal, \@rowData;
          $fetched++;
      }
-     Trace("$fetched rows returned in GetAll.") if T(SQL => 4);
      # Return the resulting list.
      return @retVal;
  }
-Line 3558
+Line 3815
      return $retVal;
  }
+ =head3 WikiNote
+ Convert a note or comment to Wiki text by replacing some bulletin-board codes with HTML. The codes
+ supported are C<[b]> for B<bold>, C<[i]> for I<italics>, and C<[p]> for a new paragraph.
+ Except for C<[p]>, all the codes are closed by slash-codes. So, for
+ example, C<[b]Feature[/b]> displays the string C<Feature> in boldface.
+     my $wikiText = ERDB::WikiNote($dataString);
+ =over 4
+ =item dataString
+ String to convert to Wiki text.
+ =item RETURN
+ An Wiki text string derived from the input string.
+ =back
+ =cut
+ sub WikiNote {
+     # Get the parameter.
+     my ($dataString) = @_;
+     # HTML-escape the text.
+     my $retVal = CGI::escapeHTML($dataString);
+     # Substitute the bulletin board codes.
+     my $italic = WikiTools::ItalicCode();
+     $retVal =~ s/\[\/?i\]/$italic/g;
+     my $bold = WikiTools::BoldCode();
+     $retVal =~ s/\[\/?b\]/$bold/g;
+     # Paragraph breaks are the same no matter which Wiki you're using.
+     $retVal =~ s!\[p\]!\n\n!g;
+     # Now we do the links, which are complicated by the need to know two
+     # things: the target URL and the text.
+     while ($retVal =~ /\[link\s+([^\]]+)\]([^\[]+)\[\/link\]/g) {
+         # Replace the matched string with the Wiki markup for links. Note that
+         # $-[0] is the starting position of the match for the entire expression,
+         # and $+[0] is past the ending position.
+         substr $retVal, $-[0], $+[0] - $-[0], WikiTools::LinkMarkup($1, $2);
+     }
+     # Return the result.
+     return $retVal;
+ }
  =head3 BeginTran
      $erdb->BeginTran();
-Line 3840
+Line 4144
  =over 4
+ =item indexObject
  ERDB XML structure for an index.
  =item RETURN
-Line 4499
+Line 4805
      # be a null string.
      if ($fileName ne "") {
          # Load the relation from the file.
-         $retVal = $self->LoadTable($fileName, $relationName, $rebuild);
+         $retVal = $self->LoadTable($fileName, $relationName, truncate => $rebuild);
      } elsif ($rebuild) {
          # Here we are rebuilding, but no file exists, so we just re-create the table.
          $self->CreateTable($relationName, 1);
-Line 5246
+Line 5552
      return $retVal;
  }
- =head2 HTML Documentation Utility Methods
+ =head2 Documentation Utility Methods
  =head3 _ComputeRelationshipSentence
-Line 5278
+Line 5584
      # Get the parameters.
      my ($relationshipName, $relationshipStructure) = @_;
      # Format the relationship sentence.
-     my $result = "$relationshipStructure->{from} <b>$relationshipName</b> $relationshipStructure->{to}";
+     my $result = "$relationshipStructure->{from} $relationshipName $relationshipStructure->{to}";
      # Compute the arity.
      my $arityCode = $relationshipStructure->{arity};
      my $arity = $ArityTable{$arityCode};
-Line 5323
+Line 5629
      return $result;
  }
+ =head3 _WikiRelationTable
+ Generate the Wiki text for a particular relation. The relation's data will be formatted as a
+ table with three columns-- the field name, the field type, and the field description.
+ This is a static method.
+ =over 4
+ =item relationName
+ Name of the relation being formatted.
+ =item relationData
+ Hash containing the relation's fields and indexes.
+ =item RETURN
+ Returns a Wiki string that can be used to display the relation name and all of its fields.
+ =back
+ =cut
+ sub _WikiRelationTable {
+     # Get the parameters.
+     my ($relationName, $relationData) = @_;
+     # We'll create a list of lists in here, then call WikiTools::Table to
+     # convert it into a table.
+     my @rows = ();
+     # Push in the header row.
+     push @rows, [qw(Field Type Description)];
+     # Loop through the fields.
+     for my $field (@{$relationData->{Fields}}) {
+         # Create this field's row. We always have a name and type.
+         my @row = ($field->{name}, $field->{type});
+         # If we have a description, add it as the third column.
+         if (exists $field->{Notes}) {
+             push @row, WikiNote($field->{Notes}->{content});
+         }
+         # Push this row onto the table list.
+         push @rows, \@row;
+     }
+     # Store the rows as a Wiki table with a level-4 heading.
+     my $retVal = join("\n\n", WikiTools::Heading(4, "$relationName Table"),
+                       WikiTools::Table(@rows));
+     # Now we show the relation's indexes. These are formatted as another
+     # table.
+     @rows = ();
+     # Push in the header row.
+     push @rows, [qw(Index Unique Fields Notes)];
+     # Get the index hash.
+     my $indexTable = $relationData->{Indexes};
+     # Loop through the indexes. For an entity, there is always at least one index.
+     # For a relationship, there are at least two. The upshot is we don't need to
+     # worry about accidentally generating a frivolous table here.
+     for my $indexName (sort keys %$indexTable) {
+         my $indexData = $indexTable->{$indexName};
+         # Determine whether or not the index is unique.
+         my $unique = ((exists $indexData->{Unique} && $indexData->{Unique} eq "true") ?
+                       "yes" : "");
+         # Get the field list.
+         my $fields = join(', ', @{$indexData->{IndexFields}});
+         # Get the note text.
+         my $description = "";
+         if (my $note = $indexData->{Notes}) {
+             $description = WikiNote($note->{content});
+         }
+         # Format this row.
+         my @row = ($indexName, $unique, $fields, $description);
+         push @rows, \@row;
+     }
+     # Add the index list to the result.
+     $retVal .= "\n\n" . WikiTools::Table(@rows);
+ }
  =head3 _ShowRelationTable
  Generate the HTML string for a particular relation. The relation's data will be formatted as an HTML
-Line 5496
+Line 5879
      return $htmlString;
  }
+ =head3 _ObjectNotes
+     my @noteParagraphs = _ObjectNotes($objectData);
+ Return a list of the notes and asides for an entity or relationship in
+ Wiki format.
+ =over 4
+ =item objectData
+ The metadata for the desired entity or relationship.
+ =item RETURN
+ Returns a list of text paragraphs in Wiki markup form.
+ =back
+ =cut
+ sub _ObjectNotes {
+     # Get the parameters.
+     my ($objectData) = @_;
+     # Declare the return variable.
+     my @retVal;
+     # Loop through the types of notes.
+     for my $noteType (qw(Notes Asides)) {
+         my $text = $objectData->{$noteType};
+         if ($text) {
+             push @retVal, "", WikiNote($text->{content});
+         }
+     }
+     # Return the result.
+     return @retVal;
+ }
 ;

 Legend:



Removed from v.1.94
 


changed lines


 
Added in v.1.103
 Legend:



Removed from v.1.94
 


changed lines


 
Added in v.1.103
-Removed from v.1.94
+Added in v.1.103

MCS Webmaster	ViewVC Help
Powered by ViewVC 1.0.3