<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">###########################################################################
#
# GreenstoneSQLPlugin.pm -- reads into doc_obj from SQL db and docsql.xml
# Metadata and/or fulltext are stored in SQL db, the rest may be stored in
# the docsql .xml files.
# A component of the Greenstone digital library software
# from the New Zealand Digital Library Project at the 
# University of Waikato, New Zealand.
#
# Copyright (C) 2001 New Zealand Digital Library Project
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
#
###########################################################################

package GreenstoneSQLPlugin;


use strict;
no strict 'refs'; # allow filehandles to be variables and viceversa

use DBI;
use docprint; # for new unescape_text() subroutine
use GreenstoneXMLPlugin;
use gsmysql;

#use unicode;
#use Encode;

########################################################################################

# GreenstoneSQLPlugin inherits from GreenstoneXMLPlugin so that if meta or fulltext
# is still written out to doc.xml (docsql .xml), that will be processed as usual,
# whereas GreenstoneSQLPlugin will process all the rest (full text and/or meta, whichever
# is written out by GreenstoneSQLPlugout into the SQL db).


sub BEGIN {
    @GreenstoneSQLPlugin::ISA = ('GreenstoneXMLPlugin');
}

# This plugin must be in the document plugins pipeline IN PLACE OF GreenstoneXMLPlugin
# So we won't have a process exp conflict here.
# The structure of docsql.xml files is identical to doc.xml and the contents are similar except:
#   - since metadata and/or fulltxt are stored in mysql db instead, just XML comments indicating
#   this are left inside docsql.xml within the &lt;Description&gt; (for meta) and/or &lt;Content&gt; (for txt)
#   - the root element Archive now has a docoid attribute: &lt;Archive docoid="OID"&gt;
sub get_default_process_exp {
    my $self = shift (@_);

    return q^(?i)docsql(-\d+)?\.xml$^; # regex based on this method in GreenstoneXMLPlugin
}

my $process_mode_list =
    [ { 'name' =&gt; "meta_only",
        'desc' =&gt; "{GreenstoneSQLPlug.process_mode.meta_only}" },      
      { 'name' =&gt; "text_only",
        'desc' =&gt; "{GreenstoneSQLPlug.process_mode.text_only}" },
      { 'name' =&gt; "all",
        'desc' =&gt; "{GreenstoneSQLPlug.process_mode.all}" } ];

my $rollback_on_cancel_list =
    [ { 'name' =&gt; "true",
        'desc' =&gt; "{common.true}" },      
      { 'name' =&gt; "false",
        'desc' =&gt; "{common.false}" } ];

# NOTE: If subclassing gsmysql for other supporting databases and if they have different required
# connection parameters, we can check how WordPlugin, upon detecting Word is installed,
# dynamically loads Word specific configuration options.
my $arguments =
    [ { 'name' =&gt; "process_exp",
	'desc' =&gt; "{BaseImporter.process_exp}",
	'type' =&gt; "regexp",
	'deft' =&gt; &amp;get_default_process_exp(),
	'reqd' =&gt; "no" },
      { 'name' =&gt; "process_mode", 
	'desc' =&gt; "{GreenstoneSQLPlug.process_mode}",
	'type' =&gt; "enum",
	'list' =&gt; $process_mode_list,
	'deft' =&gt; "all",
	'reqd' =&gt; "no"},
      { 'name' =&gt; "rollback_on_cancel", 
	'desc' =&gt; "{GreenstoneSQLPlug.rollback_on_cancel}",
	'type' =&gt; "enum",
	'list' =&gt; $rollback_on_cancel_list,
	'deft' =&gt; "false", # better default than true
	'reqd' =&gt; "no",
	'hiddengli' =&gt; "no"},
      { 'name' =&gt; "db_driver", 
	'desc' =&gt; "{GreenstoneSQLPlug.db_driver}",
	'type' =&gt; "string",	
	'deft' =&gt; "mysql",
	'reqd' =&gt; "yes"},
      { 'name' =&gt; "db_client_user", 
	'desc' =&gt; "{GreenstoneSQLPlug.db_client_user}",
	'type' =&gt; "string",	
	'deft' =&gt; "root",
	'reqd' =&gt; "yes"},
      { 'name' =&gt; "db_client_pwd", 
	'desc' =&gt; "{GreenstoneSQLPlug.db_client_pwd}",
	'type' =&gt; "string",
	'deft' =&gt; "",
	'reqd' =&gt; "no"}, # pwd not required: can create mysql accounts without pwd
      { 'name' =&gt; "db_host", 
	'desc' =&gt; "{GreenstoneSQLPlug.db_host}",
	'type' =&gt; "string",
	'deft' =&gt; "127.0.0.1", # NOTE: make this int? No default for port, since it's not a required connection param
	'reqd' =&gt; "yes"},
      { 'name' =&gt; "db_port", 
	'desc' =&gt; "{GreenstoneSQLPlug.db_port}",
	'type' =&gt; "string", # NOTE: make this int? No default for port, since it's not a required connection param
	'reqd' =&gt; "no"}
    ];

my $options = { 'name'     =&gt; "GreenstoneSQLPlugin",
		'desc'     =&gt; "{GreenstoneSQLPlugin.desc}",
		'abstract' =&gt; "no",
		'inherits' =&gt; "yes",
	        'args'     =&gt; $arguments };


###### Methods called during buildcol and import #######

sub new {
    my ($class) = shift (@_);
    my ($pluginlist,$inputargs,$hashArgOptLists) = @_;
    push(@$pluginlist, $class);

    push(@{$hashArgOptLists-&gt;{"ArgList"}},@{$arguments});
    push(@{$hashArgOptLists-&gt;{"OptList"}},$options);

    my $self = new GreenstoneXMLPlugin($pluginlist, $inputargs, $hashArgOptLists);

    
    #return bless $self, $class;
    $self = bless $self, $class;
    if ($self-&gt;{'info_only'}) {
	# If running pluginfo, we don't need to go further.
	return $self;
    }

    # do anything else that needs to be done here when not pluginfo
    
    return $self;
}

# Call init() not begin() because there can be multiple plugin passes and begin() called for
# each pass (one for doc level and another for section level indexing), whereas init() should
# be called before any and all passes.
# This way, we can connect to the SQL database once per buildcol run.
# Although now it doesn't matter, since gsmysql.pm uses the get_instance pattern to return a
# singleton db connection, regardless of the number of gsmysql objects instantiated and
# the number of connect() calls made on them.
sub init {
    my ($self) = shift (@_);
    
    $self-&gt;SUPER::init(@_); # super (GreenstoneXMLPlugin) will not yet be trying to read from doc.xml (docsql .xml) files in init().


    # create gsmysql object.
    # collection name will be used for naming tables (site name will be used for naming database)
    my $gs_sql = new gsmysql({
	'collection_name' =&gt; $ENV{'GSDLCOLLECTION'},
	'verbosity' =&gt; $self-&gt;{'verbosity'} || 0
			   });
    
    # if autocommit is set, there's no rollback support
    my $autocommit = ($self-&gt;{'rollback_on_cancel'} eq "false") ? 1 : 0;

    # try connecting to the mysql db, die if that fails
    if(!$gs_sql-&gt;connect_to_db({
	'db_driver' =&gt; $self-&gt;{'db_driver'},
	'db_client_user' =&gt; $self-&gt;{'db_client_user'},
	'db_client_pwd' =&gt; $self-&gt;{'db_client_pwd'},
	'db_host' =&gt; $self-&gt;{'db_host'},
	'db_port' =&gt; $self-&gt;{'db_port'}, # undef by default, can leave as is
	'autocommit' =&gt; $autocommit
			       })
	)
    {
	# This is fatal for the plugout, let's terminate here
	# PrintError would already have displayed the warning message on connection fail	
	die("Could not connect to db. Can't proceed.\n");
    }
    
    my $db_name = $self-&gt;{'site'} || "greenstone2"; # one database per GS3 site, for GS2 the db is called greenstone2

    # Attempt to use the db, create it if it doesn't exist (but don't create the tables yet)
    # Bail if we can't use the database
    if(!$gs_sql-&gt;use_db($db_name)) {
	
	# This is fatal for the plugout, let's terminate here after disconnecting again
	# PrintError would already have displayed the warning message on load fail
	# And on die() perl will call gsmysql destroy which will ensure a disconnect() from db
	die("Could not use db $db_name. Can't proceed.\n");
    }
    
    
    # store db handle now that we're connected
    $self-&gt;{'gs_sql'} = $gs_sql;    
}


# This method also runs on import.pl if gs_sql has a value.
# Call deinit() not end() because there can be multiple plugin passes:
# one for doc level and another for section level indexing
# and deinit() should be called before all passes
# This way, we can close the SQL database once per buildcol run.
# Again, this doesn't matter because we gsmysql the ensures the connection
# is a singleton connection instance, which connects once and disconnects once per perl process.
sub deinit {
    my ($self) = shift (@_);
    
    if($self-&gt;{'gs_sql'}) {

	# Important to call finished():
	# it will disconnect from db if this is the last gsmysql instance,
	# and it will commit to db before disconnecting if rollbback_on_cancel turned on
	$self-&gt;{'gs_sql'}-&gt;finished();

	# Clear gs_sql (setting key to undef has a different meaning from deleting:
	# undef makes key still exist but its value is unded whereas delete deletes the key)
	# So all future use has to make the connection again
	delete $self-&gt;{'gs_sql'};
    }

    $self-&gt;SUPER::deinit(@_);
}



###### Methods only called during import.pl #####

# This is called once if removeold is set with import.pl. Most plugins will do
# nothing but if a plugin does any stuff outside of creating doc obj, then 
# it may need to clear something.
# In the case of GreenstoneSQL plugs: this is the first time we have a chance
# to purge the tables of the current collection from the current site's database
sub remove_all {
    my $self = shift (@_);
    my ($pluginfo, $base_dir, $processor, $maxdocs) = @_;

    $self-&gt;SUPER::remove_all(@_);
    
    print STDERR "   Building with removeold option set, so deleting current collection's tables if they exist\n" if($self-&gt;{'verbosity'});
    
    # if we're in here, we'd already have run 'use database &lt;site&gt;;' during sub init()
    # so we can go ahead and delete the collection's tables
    my $gs_sql = $self-&gt;{'gs_sql'};
    $gs_sql-&gt;delete_collection_tables(); # will delete them if they exist

    # and recreate tables? No. Tables' existence is ensured in GreenstoneSQLPlugout::begin()
    my $proc_mode = $self-&gt;{'process_mode'};
    if($proc_mode ne "text_only") {
	$gs_sql-&gt;ensure_meta_table_exists();
    }
    if($proc_mode ne "meta_only") {
	$gs_sql-&gt;ensure_fulltxt_table_exists();
    }

}

# This is called during import.pl per document for docs that have been deleted from the 
# collection. Most plugins will do nothing
# but if a plugin does any stuff outside of creating doc obj, then it may need
# to clear something.
# In the case of GreenstoneSQL plugs: Remove the doc(s) denoted by oids from GS SQL db.
# This takes care of incremental deletes (docs marked D by ArchivesInfPlugin when building
# incrementally) as well as cases of "Non-icremental Delete", see ArchivesInfPlugin.pm.
# As well as cases involving reindexing, which are implemented here as delete followed by add.
sub remove_one {
    my $self = shift (@_);
    
    my ($file, $oids, $archivedir) = @_;

    my $rv = $self-&gt;SUPER::remove_one(@_);
    
    print STDERR "@@@ IN SQLPLUG::REMOVE_ONE: $file\n";
    
    #return undef unless $self-&gt;can_process_this_file($file); # NO, DON'T DO THIS (inherited remove_one behaviour) HERE: 
           # WE DON'T CARE IF IT'S AN IMAGE FILE THAT WAS DELETED.
           # WE CARE ABOUT REMOVING THE DOC_OID OF THAT IMAGE FILE FROM THE SQL DB
           # SO DON'T RETURN IF CAN'T_PROCESS_THIS_FILE
    
    
    my $gs_sql = $self-&gt;{'gs_sql'} || return 0; # couldn't make the connection or no db etc
    
    my $proc_mode = $self-&gt;{'process_mode'};
    foreach my $oid (@$oids) {	
	if($proc_mode eq "all" || $proc_mode eq "meta_only") {
	    print STDERR "@@@@@@@@ Deleting $oid from meta table\n" if $self-&gt;{'verbosity'} &gt; 2;
	    $gs_sql-&gt;delete_recs_from_metatable_with_docid($oid);
	}
	if($proc_mode eq "all" || $proc_mode eq "text_only") {
	    print STDERR "@@@@@@@@ Deleting $oid from fulltxt table\n" if $self-&gt;{'verbosity'} &gt; 2;
	    $gs_sql-&gt;delete_recs_from_texttable_with_docid($oid);
	}
    }
    return $rv;
}

##### Methods called only during buildcol #####

sub xml_start_tag {
    my $self = shift(@_);
    my ($expat, $element) = @_;

    my $outhandle = $self-&gt;{'outhandle'};
    
    $self-&gt;{'element'} = $element;
    if ($element eq "Archive") { # docsql.xml files contain a OID attribute on Archive element
	# the element's attributes are in %_ as per ReadXMLFile::xml_start_tag() (while $_
	# contains the tag)

	# Don't access %_{'docoid'} directly: keep getting a warning message to 
	# use $_{'docoid'} for scalar contexts, but %_ is the element's attr hashmap 
	# whereas $_ has the tag info. So we don't want to do $_{'docoid'}.
	my %attr_hash = %_; # right way, see OAIPlugin.pm
	$self-&gt;{'doc_oid'} = $attr_hash{'docoid'};
	print $outhandle "Extracted OID from docsql.xml: ".$self-&gt;{'doc_oid'}."\n"
	    if $self-&gt;{'verbosity'} &gt; 2;

    }
    else { # let superclass GreenstoneXMLPlugin continue to process &lt;Section&gt; and &lt;Metadata&gt; elements
	$self-&gt;SUPER::xml_start_tag(@_);
    }
}

# There are multiple passes processing the document (see buildcol's mode parameter description):
# - compressing the text which may be a dummy pass for lucene/solr, wherein they still want the
# docobj for different purposes,
# - the pass(es) for indexing, e.g. doc/didx and section/sidx level passes
# - and an infodb pass for processing the classifiers. This pass too needs the docobj
# Since all passes need the doc_obj, all are read in from docsql + SQL db into the docobj in memory

# We only ever get here or do any parsing of the docsql.xml file during the buildcol.pl phase.
# At the end of superclass GreenstoneXMLPlugin.pm's close_document() method,
# the doc_obj in memory is processed (indexed) and then made undef.
# So we have to work with doc_obj before superclass close_document() is finished.
sub close_document {
    my $self = shift(@_);

    my $gs_sql = $self-&gt;{'gs_sql'};
    
    my $outhandle = $self-&gt;{'outhandle'};
    my $doc_obj = $self-&gt;{'doc_obj'};

    my $oid = $self-&gt;{'doc_oid'}; # we stored current doc's OID during sub xml_start_tag()
    my $proc_mode = $self-&gt;{'process_mode'};
    
    # For now, we have access to doc_obj (until just before super::close_document() terminates)

    # OID parsed of docsql.xml file does need to be set on $doc_obj, as noticed in this case:
    # when a doc in import is renamed, and you do incremental import, it is marked for reindexing 
    # (reindexing is implemented by this plugin as a delete followed by add into the sql db).
    # In that case, UNLESS you set the OID at this stage, the old deleted doc id (for the old doc
    # name) continues to exist in the index at the end of incremental rebuilding if you were to
    # browse the rebuilt collection by files/titles. So unless you set the OID here, the deleted
    # doc oids will still be listed in the index.
	
    print STDERR "   GreenstoneSQLPlugin processing doc $oid (reading into docobj from SQL db)\n"
    	if $self-&gt;{'verbosity'};
    
    my $build_proc_mode = $self-&gt;{'processor'}-&gt;get_mode(); # can be "text" as per basebuildproc or infodb
    if($build_proc_mode =~ m/(delete)$/) {
	# build_proc_mode could be "(infodb|text)(delete|reindex)"
	# "...delete" or "...reindex" as per ArchivesInfPlugin
	# But reindex is implemented as delete for GreenstoneSQLPlugs, so that's all we see here?
	print STDERR "   DOC $oid WAS MARKED FOR DELETION. Won't attempt to retrieve from SQL db.\n" if $self-&gt;{'verbosity'};
	$self-&gt;{'doc_obj'}-&gt;set_OID($oid); # oid is all we care about for a doc marked for deletion
	$self-&gt;SUPER::close_document(@_); # at the end of this method, doc will have been deleted
	return;	 # oid of doc marked for deletion is not in the SQL db, don't bother looking it up
    }

    # else, doc denoted by oid was not marked for deletion, look up its oid in db and read it into doc obj
    
    if($proc_mode eq "all" || $proc_mode eq "meta_only") {
	# read in meta for the collection (i.e. select * from &lt;col&gt;_metadata table
	
	my $records = $gs_sql-&gt;select_from_metatable_matching_docid($oid, $outhandle);
	
	print $outhandle "----------SQL DB contains meta-----------\n" if $self-&gt;{'verbosity'} &gt; 2;

	foreach my $row (@$records) {
	    my ($primary_key, $did, $sid, $metaname, $metaval) = @$row;
		
	    # get rid of the artificial "root" introduced in section id when saving to sql db
	    $sid =~ s@^root@@;
	    $sid = $doc_obj-&gt;get_top_section() unless $sid;
	    print $outhandle "### did: $did, sid: |$sid|, meta: $metaname, val: $metaval\n"
		if $self-&gt;{'verbosity'} &gt; 2;
	    
	    # We're only dealing with utf8 data where docobj is concerned
	    # Data stored unescaped in db: escaping only for html/xml files, not for txt files or db
	    $doc_obj-&gt;add_utf8_metadata($sid, $metaname, $metaval);
	}
	
	# UTF8 debugging, e.g. if we have a with macron in dc.Title
	##binmode(STDERR, ":utf8"); # not necessary when calling utf8decomp to print wide characters as unicode codept, avoiding 'wide character' warnings.
	#my $dcTitle = $doc_obj-&gt;get_metadata_element($doc_obj-&gt;get_top_section(), "dc.Title");	
	#print STDERR "###### dc.Title: ".&amp;unicode::utf8decomp($dcTitle)."\n";
	#print STDERR "###### DECODED dc.Title: ".&amp;unicode::utf8decomp(&amp;Encode::decode_utf8($dcTitle))."\n"; # decoding was needed for perl 5.18
	
	print $outhandle "----------FIN READING DOC's META FROM SQL DB------------\n"
	    if $self-&gt;{'verbosity'} &gt; 2;
    }
	
    if($proc_mode eq "all" || $proc_mode eq "text_only") {
	# read in fulltxt for the collection (i.e. select * from &lt;col&gt;_fulltxt table
	
	my $fulltxt_table = $gs_sql-&gt;get_fulltext_table_name();
	
	
	my $records = $gs_sql-&gt;select_from_texttable_matching_docid($oid, $outhandle);
	
	
	print $outhandle "----------\nSQL DB contains txt entries for-----------\n"
	    if $self-&gt;{'verbosity'} &gt; 2;

	foreach my $row (@$records) {
	    my ($primary_key, $did, $sid, $text) = @$row;
	    
	    # get rid of the artificial "root" introduced in section id when saving to sql db
	    #$sid =~ s@^root@@;
	    $sid = $doc_obj-&gt;get_top_section() if ($sid eq "root");
	    print $outhandle "### did: $did, sid: |$sid|, fulltext: &lt;TXT&gt;\n"
		if $self-&gt;{'verbosity'} &gt; 2;

	    # We're only dealing with utf8 data where docobj is concerned
	    # Data stored unescaped in db: escaping is only for html/xml files, not for txt files or db
	    $doc_obj-&gt;add_utf8_textref($sid, \$text);
	}	
	print $outhandle "----------FIN READING DOC's TXT FROM SQL DB------------\n"
	    if $self-&gt;{'verbosity'} &gt; 2;
    }
    

    # setting OID here instead of before reading from SQL db into docobj, will prevent duplicate values for Identifier
    # since doc::set_OID() calls doc::set_metadata_element() for metadata that can't occur more than once
    $self-&gt;{'doc_obj'}-&gt;set_OID($oid); # may only be necessary if doc was marked for deletion so that SUPER::close_document knows
                                       # the oid of marked doc to remove from index
    
    # done reading into docobj from SQL db
	
    # don't forget to clean up on close() in superclass
    # It will get the doc_obj indexed then make it undef
    $self-&gt;SUPER::close_document(@_);
}


1;
</pre></body></html>