# Apache::NSDL::ToTheGateway
#
# ToTheGateway.pm
# API for passing information from NSDL to the Gateway Server
#
# For more documentation, read the POD documentation
# of this module with the perldoc command:
#
#         perldoc ./ToTheGateway.pm
#
# Brief description
# =================
#
# This module contains functionality for
# transferring information from NSDL to the Gateway Server.
#
# In terms of the overall data flow, the
# '=====>' below indicates the role of this
# module.
#
# NSDL =========> Gateway --------> LON-CAPA
# LON-CAPA -----> Gateway --------> NSDL
#
# SUBROUTINES:
# NSDL->answer_list_records_request
# NSDL->answer_search_request
# NSDL->answer_metadata_record_request
# NSDL->answer_resource_request

# Year 2002
# Scott Harrison
# February-May
#
###

package Apache::NSDL::ToTheGateway;

# ================================================================ DEPENDENCIES
use strict; # enforce handling of variables, references and subroutines
use Apache::Constants qw(:common);
use Apache::GATEWAY::Common;
use Apache::NSDL::FromTheGateway;

# ============================================================ MODULE VARIABLES
my $VERSION = sprintf("%d.%02d", q$Revision: 1.5 $ =~ /(\d+)\.(\d+)/);

# ================================================================= SUBROUTINES

# ----------------------------- Handling routine called via Apache and mod_perl
sub handler {
    my $r = shift;
    Apache::GATEWAY::Common::readCGI($r);
    my $output;
    if ($ENV{'form.verb'} eq 'GetRecord') {
	$output=
      Apache::NSDL::FromTheGateway::view_LONCAPAgateway_metadata_record(\%ENV);
    }
    elsif ($ENV{'form.verb'} eq 'Identify') {
	my $responseDate=Apache::GATEWAY::Common::responseDate();
	$output=(<<END);
<?xml version="1.0" encoding="UTF-8"?>
  <Identify 
     xmlns="http://www.openarchives.org/OAI/1.1/OAI_Identify"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/OAI_Identify
                         http://www.openarchives.org/OAI/1.1/OAI_Identify.xsd">
    <responseDate>$responseDate</responseDate>
    <requestURL>http://nsdl.lon-capa.org/OAI-script?verb=Identify</requestURL>
    <repositoryName>The LearningOnline Network with CAPA</repositoryName>
    <baseURL>http://nsdl.lon-capa.org/OAI-script</baseURL>
    <protocolVersion>1.1</protocolVersion>
    <adminEmail>mailto:korte&#x0040;lite.msu.edu</adminEmail>
    <description>
     <oai-identifier xmlns="http://www.openarchives.org/OAI/1.1/oai-identifier"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/oai-identifier
                       http://www.openarchives.org/OAI/1.1/oai-identifier.xsd">
        <scheme>oai</scheme>
        <repositoryIdentifier>loncapa</repositoryIdentifier>
        <delimiter>:</delimiter>
        <sampleIdentifier>oai:loncapa:harrison2002-1</sampleIdentifier>
      </oai-identifier>
    </description>
    <description>
      <eprints xmlns="http://www.openarchives.org/OAI/1.1/eprints"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.openarchives.org/OAI/1.1/eprints
                              http://www.openarchives.org/OAI/1.1/eprints.xsd">
        <content>
          <URL>http://nsdl.lon-capa.org/info/content.htm</URL>
        </content>
        <metadataPolicy>
          <text>Metadata can be used by authorized users</text>
          <URL>http://nsdl.lon-capa.org/metadata_use.htm</URL>
        </metadataPolicy>
        <dataPolicy>
       <text>Full content, i.e. preprints may not be harvested by robots</text>
        </dataPolicy>
        <submissionPolicy>
          <URL>http://nsdl.lon-capa.org/info/submission.htm</URL>
        </submissionPolicy>
      </eprints>
    </description>
  </Identify> 
END
    }
    elsif ($ENV{'form.verb'} eq 'ListIdentifiers') {
	$output='not yet implemented';
    }
    elsif ($ENV{'form.verb'} eq 'ListMetadataFormats') {
	$output='not yet implemented';
    }
    elsif ($ENV{'form.verb'} eq 'ListRecords') {
	$output='not yet implemented';
    }
    elsif ($ENV{'form.verb'} eq 'ListSets') {
	$output='not yet implemented';
    }
    $output=~s/\>/\&gt;/g;
    $output=~s/\</\&lt;/g;
    my $cgi;
    foreach my $key (keys %ENV) {
	if ($key=~/^form\./) {
	    $cgi.="$key: $ENV{$key}\n";
	}
    }
    $r->content_type('text/html');
    $r->send_http_header;
    return(OK) if $r->header_only;
    $r->print(<<END);
<html>
<head><title>Test Output</title></head>
<body>
<h1>Apache::NSDL::ToTheGateway</h1>
<h2>Input</h2>
<pre>
$cgi
</pre>
<h2>Output</h2>
<pre>
$output
</pre>
</body>
</html>
END
    return(OK);
}

# ------------------------------------------- NSDL->answer_list_records_request
sub answer_list_records_request {
# Not yet implemented
# Need to specifically characterize INPUT arguments and OUTPUT data
}

# ------------------------------------------------- NSDL->answer_search_request
sub answer_search_request {
    my ($url)=@_;
    return "will have http querying strategy against NSDL servers\n";
}

# ---------------------------------------- NSDL->answer_metadata_record_request
sub answer_metadata_record_request {
    my ($eref)=@_;
    return Apache::NSDL::FromTheGateway($eref);
}

# ----------------------------------------------- NSDL->answer_resource_request
sub answer_resource_request {
# Not yet implemented
# Need to specifically characterize INPUT arguments and OUTPUT data
}

1;

__END__

=pod

=head1 NAME

B<Apache::NSDL::ToTheGateway> - API for passing information from NSDL to the Gateway Server

=head1 SYNOPSIS

 use Apache::NSDL::ToTheGateway;

 my $arrayref=
    Apache::NSDL::ToTheGateway::answer_list_records_request
      ($OAI_protocol_request);

=head1 DESCRIPTION

This module contains functionality for
transferring information from NSDL to the Gateway Server.

In terms of the overall data flow, the
'=====>' below indicates the role of this
module.

B<NSDL =========E<gt> Gateway> --------E<gt> LON-CAPA

LON-CAPA -----E<gt> Gateway --------E<gt> NSDL

=head2 EXIT CODES

The subroutines of this module all output an exit code which
describes the status of function completion.  The exit code
may be followed by a more descriptive message such as:

 FORMATERROR:Sun May  5 20:15:16 GMT 2002:missing 'protocol://' pattern

=over 4

=item *

B<'SUCCESS'>, information was found and is being returned

=item *

B<'EMPTY'>, everything functioned properly, but no information was present

=item *

B<'BADEMPTY'>, everything appeared to function properly, but no information
was present (which defies expectation); this is useful for detecting phantom
cases of connectivity when verifying test cases of vertical software partitions

=item *

B<'TIMEOUT'>, the request is taking WAY too long

=item *

B<'FORMATERROR'>, the input argument is not formatted correctly in a way that
can be processed by the NSDL server

=item *

B<'CONNECTIONFAILURE'>, the NSDL server cannot be contacted

=back

=head2 SUBROUTINES

Note that the subroutines all output an exit code which
describes the status of function completion.

In the case of failed function completion, the other
output argument(s) will typically only be 'NULL' values.

=over 4

=item B<Apache::NSDL::answer_list_records_request>

=over 4

=item B<Input> - Scalar string

Take in an OAI-format request for a specific NSDL server.

=item B<Output> - Scalar string, Scalar array reference

An exit code is returned as a scalar string.

A list of records returned via an array reference.

=item B<Description>

This lists the records matching a given request.
The request comes from the Gateway Server, B<and the information
passes from NSDL I<to the> GATEWAY>.

=item B<Status of Implementation>

n/a

=back

=item B<Apache::NSDL::answer_search_request>

=over 4

=item B<Input> - Scalar string

Take in an OAI-format request for a specific NSDL server (a search expression
is passed).

=item B<Output> - Scalar string, Scalar array reference

An exit code is returned as a scalar string.

A list of relevant records (matching the search request) returned via an
array reference.

=item B<Description>

This lists the records matching a given search request.
The request comes from the Gateway Server, B<and the information
passes from NSDL I<to the> GATEWAY>.

=item B<Status of Implementation>

n/a

=back

=item B<Apache::NSDL::answer_metadata_record_request>

=over 4

=item B<Input> - Scalar string

Take in an OAI-format request for a specific NSDL server resource's
metadata.

=item B<Output> - Scalar string, Scalar string reference

An exit code is returned as a scalar string.

The metadata entries for the resource; returned via a scalar reference.

=item B<Description>

This lists the records matching a given request.
The request comes from the Gateway Server, B<and the information
passes from NSDL I<to the> GATEWAY>.

=item B<Status of Implementation>

n/a

=back

=item B<Apache::NSDL::answer_resource_request>

=over 4

=item B<Input> - Scalar string

Take in an OAI-format request for a specific NSDL server's
resource content.

=item B<Output> - Scalar string, Scalar string reference

An exit code is returned as a scalar string.

A reference to the resource content (now physically present in computer
memory).

=item B<Description>

This provides the content of the resource matching a given request.
The request comes from the Gateway Server, B<and the information
passes from NSDL I<to the> GATEWAY>.

=item B<Status of Implementation>

n/a

=back

=back

=head1 README

B<Apache::NSDL::ToTheGateway>
is part of the NSDL-LONCAPA Gateway Server system.
Please see http://nsdl.lon-capa.org/ for more information.

=head1 AUTHOR

Scott Harrison, 2002

=head1 PREREQUISITES

This module requires the C<strict> module.

=head1 COREQUISITES

Apache::NSDL::FromTheGateway
Apache::GATEWAY::ToNSDL
Apache::GATEWAY::FromNSDL
Apache::GATEWAY::ToLONCAPA
Apache::GATEWAY::FromLONCAPA
Apache::LONCAPA::FromTheGateway
Apache::LONCAPA::ToTheGateway

=head1 SEE ALSO

http://www.lon-capa.org/

http://www.smete.org/

Also visit the other Apache::NSDL::*, Apache::LONCAPA::*,
and Apache::GATEWAY::* manpages.

=head1 OSNAMES

linux

=cut