new()

    my $harvester = Net::OAI::Harvester->new(
        baseURL => 'http://memory.loc.gov/cgi-bin/oai2_0'
    );

If you want to pull down all the XML files and keep them in a directory, rather than having the stored as transient temp files pass in the dumpDir parameter.

    my $harvester = Net::OAI::Harvester->new(
        baseUrl => 'http://memory.loc.gov/cgi-bin/oai2_0',
        dumpDir => 'american-memory'
    );

Also if you would like to fine tune the HTTP client used by Net::OAI::Harvester you can pass in a configured object. For example this can be handy if you want to adjust the client timeout:

    my $ua = LWP::UserAgent->new();
    $ua->timeout(20); ## set timeout to 20 seconds
    my $harvester = Net::OAI::Harvester->new(
        baseURL     => 'http://memory.loc.gov/cgi-bin/oai2_0',
        userAgent   => $ua 
    );

identify()

    my $identity = $harvester->identify();
    print "repository name: ",$identity->repositoryName(),"\n";
    print "protocol version: ",$identity->protocolVersion(),"\n";
    print "earliest date stamp: ",$identity->earliestDatestamp(),"\n";
    print "admin email(s): ", join( ", ", $identity->adminEmail() ), "\n";
    ...

For more details see the Net::OAI::Identify documentation.

listMetadataFormats()

    my $list = $harvester->listMetadataFormats();
    print "archive supports metadata prefixes: ", 
        join( ',', $list->prefixes() ),"\n";

If you are interested in the metadata formats available for a particular resource identifier then you can pass in that identifier.

    my $list = $harvester->listMetadataFormats( identifier => '1234567' );
    print "record identifier 1234567 can be retrieved as ",
        join( ',', $list->prefixes() ),"\n";

See documentation for Net::OAI::ListMetadataFormats for more details.

getRecord()

    my $result = $harvester->getRecord( 
        identifier      => 'abc123',
    );

    ## did something go wrong?
    if ( my $oops = $result->errorCode() ) { ... };

    ## get the result as Net::OAI::Record object
    my $record = $result->record();     # undef if error

    ## directly get the Net::OAI::Record::Header object
    my $header = $result->header();     # undef if error
    ## same as
    my $header = $result->record()->header();     # undef if error

    ## get the metadata object 
    my $metadata = $result->metadata(); # undef if error or harvested with recordHandler

    ## or if you would rather use your own XML::Handler 
    ## pass in the package name for the object you would like to create
    my $result = $harvester->getRecord(
        identifier              => 'abc123',
        metadataHandler         => 'MyHandler'
    );
    my $metadata = $result->metadata();
    
    my $result = $harvester->getRecord(
        identifier              => 'abc123',
        recordHandler           => 'MyCompleteHandler'
    );
    my $complete_record = $result->recorddata(); # undef if error or harvested with metadataHandler

listRecords()

    my $records = $harvester->listRecords( 
        metadataPrefix  => 'oai_dc'
    );

    ## iterate through the results with next()
    while ( my $record = $records->next() ) { 
        my $metadata = $record->metadata();
        ...
    }

If you would like to use your own metadata handler then you can specify the package name of the handler as the "metadataHandler" (will be exposed to events below the "metadata" element) or "recordHandler" (will be exposed to the "record" element and all its children) parameter, passing either

the name of the class as string, in that case a new instance will be created for any OAI record encountered or

an already instantiated object of that class which will be reused for all records.

    my $records = $harvester->listRecords(
        metadataPrefix  => 'mods',
        metadataHandler => 'MODS::Handler'
    );

    while ( my $record = $records->next() ) { 
        my $metadata = $record->metadata();
        # $metadata will be a MODS::Handler object
    }

If you want to automatically handle resumption tokens you can achieve this with the listAllRecords() method. In this case the "next()" method transparently causes the next response to be fetched from the repository if the current response ran out of records and contained a resumptionToken.

If you prefer you can handle resumption tokens yourself with a loop, and the resumptionToken() method. You might want to do this if you are working with a repository that wants you to wait between requests or if connectivity problems become an issue during particulary long harvesting runs and you want to implement a retransmission strategy for failing requests.

    my $records = $harvester->listRecords( metadataPrefix => 'oai_dc' );
    my $responseDate = $records->responseDate();
    my $finished = 0;

    while ( ! $finished ) {

        while ( my $record = $records->next() ) { # a Net::OAI::Record object
            my $metadata = $record->metadata();
            # do interesting stuff here 
        }

        my $rToken = $records->resumptionToken();
        if ( $rToken ) { 
            $records = $harvester->listRecords( 
                resumptionToken => $rToken->token()
            );
        } else { 
            $finished = 1;
        }

    }

Please note: Since "listRecords()" stashes away the individual records it encounters with "Storable", special care has to be taken if the handlers you provided make use of XS modules since these objects cannot be reliably handled. Therefore you will have to provide the special serializing and deserializing methods "STORABLE_freeze()" and "STORABLE_thaw()" for the objects used by your filter(s).

listAllRecords()

    my $records = $harvester->listAllRecords( metadataPrefix => 'oai_dc' );

    while ( my $record = $records->next() ) { # a Net::OAI::Record object until undef
        my $metadata = $record->metadata();
        # do interesting stuff here 
    }

listIdentifiers()

    my $headers = $harvester->listIdentifiers( 
        metadataPrefix  => 'oai_dc'
    );

    ## iterate through the results with next()
    while ( my $header = $identifiers->next() ) {  # a Net::OAI::Record::Header object
        print "identifier: ", $header->identifier(), "\n";
    }

If you want to automatically handle resumption tokens use listAllIdentifiers(). If you are working with a repository that encourages pauses between requests you can handle the tokens yourself using the technique described above in listRecords().

listAllIdentifiers()

listSets()

    my $sets = $harvester->listSets();
    foreach ( $sets->setSpecs() ) { 
        print "set spec: $_ ; set name: ", $sets->setName( $_ ), "\n";
    }

baseURL()

    $harvester->baseURL( 'http://memory.loc.gov/cgi-bin/oai2_0' );

Or if you want to know what the current baseURL is

    $baseURL = $harvester->baseURL();

userAgent()