Difference between revisions of "API:EPrints/Repository"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
 
 
(30 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
+
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/Repository.pm|package_name=EPrints::Repository}}[[Category:API|Repository]]<!-- End of Pod2Wiki -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Repository.pm|package_name=EPrints::Repository}}[[Category:API|REPOSITORY]][[Category:API:EPrints/Repository|REPOSITORY]]<div><!-- Edit below this comment -->
<!-- Pod2Wiki=head_name -->=NAME=
 
'''EPrints::Repository''' - A single eprint repository
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
This class is a single eprint repository with its own configuration, database and website.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
<!-- Pod2Wiki=item_new -->==new==
+
==NAME==
 +
EPrints::Repository - connection to a single repository instance
  
  $repository = EPrints::Repository-&gt;new( $id, [$noxml] )
+
<!-- Edit below this comment -->
  
Returns the repository with the given repository ID. If $noxml is specified then it skips loading the XML based configuration files (this is needed when creating an repository as it first has to create the DTD files, and if it can't start you have a catch 22 situtation).
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_new_from_request -->==new_from_request==
+
<!-- Pod2Wiki=head_synopsis -->
 +
==SYNOPSIS==
 +
<source lang="perl">use EPrints;
  
  $repository = EPrints::Repository-&gt;new_from_request( $request )
+
$repo = EPrints->new->current_repository;
  
This creates a new repository object. It looks at the given Apache request object and decides which repository to load based on the  value of the PerlVar "EPrints_ArchiveID".
+
$repo = EPrints->new->repository( "myrepo" );
  
Aborts with an error if this is not possible.
+
$xml = $repo->xml;
 +
$cuser = $repo->current_user;
 +
$repo->log( "Got user " . $cuser->id );</source>
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_get_language -->==get_language==
 
  
  $language = $repository-&gt;get_language( [$langid] )
 
  
Returns the EPrints::Language for the requested language id (or the default for this repository if $langid is not specified).  
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_description -->
 +
==DESCRIPTION==
 +
EPrints::Repository represents a connection to the EPrints system. It connects to a single EPrints repository, and the database used by that repository.
  
<!-- End of Pod2Wiki -->
+
Each Repository has a "current language". If you are running in a  multilingual mode, this is used by the HTML rendering functions to choose what language to return text in.
<!-- Pod2Wiki=item_get_template_parts -->==get_template_parts==
 
  
  $template = $repository-&gt;get_template_parts( $langid, [$template_id] )
+
The Repository object also knows about the current apache connection, if there is one, including the CGI parameters.
  
Returns an array of utf-8 strings alternating between XML and the id of a pin to replace. This is used for the faster template construction.
+
If the connection requires a username and password then it can also  give access to the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] object representing the user who is causing this request. See [[API:EPrints/Repository#current_user|current_user]].
  
<!-- End of Pod2Wiki -->
+
The Repository object provides access to the [[API:EPrints/XML|EPrints::XML]] and [[API:EPrints/XHTML|EPrints::XHTML]] class which contain methods for creating XHTML results which can be returned via the web interface.
<!-- Pod2Wiki=item_get_template -->==get_template==
 
  
  $template = $repository-&gt;get_template( $langid, [$template_id] )
+
<!-- Edit below this comment -->
  
Returns the DOM document which is the webpage template for the given language. Do not modify the template without cloning it first.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_get_types -->==get_types==
+
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<!-- Pod2Wiki=head_new -->
 +
===new===
  
  @type_ids = $repository-&gt;get_types( $type_set )
+
<source lang="perl">$repository = EPrints::Repository->new( %opts )
  
Return an array of keys for the named set. Comes from  /cfg/types/foo.xml
+
</source>
 +
Creates and returns a new repository object. This is a utility object only and will only have the basic system configuration available.
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_get_dataset -->==get_dataset==
 
  
  $dataset = $repository-&gt;get_dataset( $setname )
 
  
Returns the cached EPrints::DataSet with the given dataset id name.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_new -->
 +
===new===
  
<!-- End of Pod2Wiki -->
+
<source lang="perl">$repository = EPrints::Repository->new( $repository_id, %opts )
<!-- Pod2Wiki=item_get_conf -->==get_conf==
 
  
  $confitem = $repository-&gt;get_conf( $key, [@subkeys] )
+
</source>
 +
Create a connection to an EPrints repository $repository_id which provides access to the database and to the repository configuration.
  
Returns a named configuration setting. Probably set in ArchiveConfig.pm
+
Options:
  
$repository-&gt;get_conf( "stuff", "en", "foo" )
+
<pre>  db_connect - 1
 +
  check_db - 1
 +
  noise - 0</pre>
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_create_from_data -->
 +
===create_from_data===
 +
 
 +
<source lang="perl">$repo = EPrints::Repository->create_from_data( $epdata )
 +
 
 +
</source>
 +
Create a new repository instance using $epdata.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_delete -->
 +
===delete===
 +
 
 +
<source lang="perl">$repo->delete()
 +
 
 +
</source>
 +
Destroy the repository and all its contents.
 +
 
 +
To allow this method you must first set $EPrints::Repository::ALLOW_DELETE to 1.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_query -->
 +
===query===
 +
 
 +
<source lang="perl">$query = $repository->query
 +
 
 +
</source>
 +
Return the {{API:PodLink|file=CGI|package_name=CGI|section=|text=CGI}} object describing the current HTTP query, or  undefined if this isn't a CGI script.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_url_param -->
 +
===url_param===
 +
 
 +
<source lang="perl">$value or @values = $repository->url_param( $name )
 +
 
 +
</source>
 +
Retrieve the UTF-8 value(s) of the query parameter $name for the current request.
 +
 
 +
This will not cause the POST data to be read.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_param -->
 +
===param===
 +
 
 +
<source lang="perl">$value or @values = $repository->param( $name )
 +
 
 +
</source>
 +
Passes through to CGI.pm param method.
 +
 
 +
$value = $repository-&gt;param( $name ): returns the value of CGI parameter $name.
 +
 
 +
@values = $repository-&gt;param: returns an array of the names of all the CGI parameters in the current request.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_xml -->
 +
===xml===
 +
 
 +
<source lang="perl">$xml = $repo->xml
 +
 
 +
</source>
 +
Return an [[API:EPrints/XML|EPrints::XML]] object for working with XML.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_xhtml -->
 +
===xhtml===
 +
 
 +
<source lang="perl">$xhtml = $repo->xhtml
 +
 
 +
</source>
 +
Return an [[API:EPrints/XHTML|EPrints::XHTML]] object for working with XHTML.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_eprint -->
 +
===eprint===
 +
 
 +
<source lang="perl">$eprint = $repository->eprint( $eprint_id );
 +
 
 +
</source>
 +
A convience method to return the [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]] with  the given ID, or undef.
 +
 
 +
Equivent to $repository-&gt;dataset("eprint")-&gt;dataobj( $eprint_id )
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_current_language -->
 +
===current_language===
 +
 
 +
<source lang="perl">$lang = $repository->current_language
 +
 
 +
</source>
 +
Returns the current language.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_current_user -->
 +
===current_user===
 +
 
 +
<source lang="perl">$user = $repository->current_user
 +
 
 +
</source>
 +
Return the current logged in [[API:EPrints/DataObj/User|EPrints::DataObj::User]] for this session.
 +
 
 +
Return undef if there isn't one.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_user -->
 +
===user===
 +
 
 +
<source lang="perl">$user = $repository->user( $user_id );
 +
 
 +
</source>
 +
A convience method to return the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] with  the given ID, or undef.
 +
 
 +
Equivent to $repository-&gt;dataset("user")-&gt;dataobj( $user_id )
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_user_by_username -->
 +
===user_by_username===
 +
 
 +
<source lang="perl">$user = $repository->user_by_username( $username );
 +
 
 +
</source>
 +
Return the user with the given username, or undef.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_user_by_email -->
 +
===user_by_email===
 +
 
 +
<source lang="perl">$user = $repository->user_by_email( $email );
 +
 
 +
</source>
 +
Return the [[API:EPrints/DataObj/User|EPrints::DataObj::User]] with the given email, or undef.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_template -->
 +
===template===
 +
 
 +
<source lang="perl">$template = $repository->template( [ $id ] )
 +
 
 +
</source>
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_dataset -->
 +
===dataset===
 +
 
 +
<source lang="perl">$dataset = $repository->dataset( $setname )
 +
 
 +
</source>
 +
Return a given [[API:EPrints/DataSet|EPrints::DataSet]] or undef if it doesn't exist.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_config -->
 +
===config===
 +
 
 +
<source lang="perl">$confitem = $repository->config( $key, [@subkeys] )
 +
 
 +
</source>
 +
Returns a named configuration setting including those defined in archvies/&lt;archive_id&gt;/cfg/cfg.d/
 +
 
 +
$repository-&gt;config( "stuff", "en", "foo" )
  
 
is equivalent to  
 
is equivalent to  
  
$repository-&gt;get_conf( "stuff" )-&gt;{en}-&gt;{foo}  
+
$repository-&gt;config( "stuff" )-&gt;{en}-&gt;{foo}  
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_log -->
 +
===log===
 +
 
 +
<source lang="perl">$repository->log( $msg [, $level ] )
 +
 
 +
</source>
 +
Log a plain text message $msg. If $level is given only logs if $level is greater than or equal to [[API:EPrints/Repository#noise|noise]].
 +
 
 +
To override where log messages are sent define the <code>log</code> callback:
  
<!-- End of Pod2Wiki -->
+
<pre> $c-&gt;{log} = sub {
<!-- Pod2Wiki=item_log -->==log==
+
    my( $repo, $msg, $level ) = @_;
 +
 
 +
    ...
 +
  };</pre>
  
  $repository-&gt;log( $msg )
+
<!-- Edit below this comment -->
  
Calls the log method from ArchiveConfig.pm for this repository with the  given parameters. Basically logs the comments wherever the site admin wants them to go. Printed to STDERR by default.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_call -->==call==
+
<!-- Pod2Wiki=head_call -->
 +
===call===
  
  $result = $repository-&gt;call( $cmd, @params )
+
<source lang="perl">$result = $repository->call( $cmd, @params )
  
 +
</source>
 
Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.
 
Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_can_call -->==can_call==
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_can_call -->
 +
===can_call===
  
  $boolean = $repository-&gt;can_call( @cmd_conf_path )
+
<source lang="perl">$boolean = $repository->can_call( @cmd_conf_path )
  
 +
</source>
 
Return true if the given subroutine exists in this repository's config package.
 
Return true if the given subroutine exists in this repository's config package.
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_try_call -->==try_call==
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_try_call -->
 +
===try_call===
  
  $result = $repository-&gt;try_call( $cmd, @params )
+
<source lang="perl">$result = $repository->try_call( $cmd, @params )
  
 +
</source>
 
Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.
 
Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.
  
Line 105: Line 342:
 
This is used to call deprecated callback subroutines.
 
This is used to call deprecated callback subroutines.
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_get_store_dirs -->==get_store_dirs==
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_template_dirs -->
 +
===template_dirs===
 +
 
 +
<source lang="perl">@dirs = $repository->template_dirs( $langid )
 +
 
 +
</source>
 +
Returns a list of directories from which template files may be sourced, where the first matching template encountered is used.
  
  @dirs = $repository-&gt;get_store_dirs
+
The directories searched are:
  
Returns a list of directories available for storing documents. These may well be symlinks to other hard drives.
+
<pre>  archives/[archiveid]/cfg/lang/[langid]/templates/
 +
  archives/[archiveid]/cfg/templates/
 +
  archives/[archiveid]/cfg/themes/[themeid]/lang/[langid]/templates/
 +
  archives/[archiveid]/cfg/themes/[themeid]/templates/
 +
  lib/themes/[themeid]/templates/
 +
  lib/lang/[langid]/templates/
 +
  lib/templates/</pre>
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_get_store_dir_size -->==get_store_dir_size==
 
  
  $size = $repository-&gt;get_store_dir_size( $dir )
 
  
Returns the current storage (in bytes) used by a given documents dir. $dir should be one of the values returned by $repository-&gt;get_store_dirs.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_get_static_dirs -->
 +
===get_static_dirs===
  
This should not be called if disable_df is set in SystemSettings.
+
<source lang="perl">@dirs = $repository->get_static_dirs( $langid )
  
<!-- End of Pod2Wiki -->
+
</source>
<!-- Pod2Wiki=item_parse_xml -->==parse_xml==
+
Returns a list of directories from which static files may be sourced.
  
  $domdocument = $repository-&gt;parse_xml( $file, $no_expand );
+
Directories are returned in order of importance, most important first:
  
Turns the given $file into a XML DOM document. If $no_expand is true then load &amp;entities; but do not expand them to the values in the DTD.
+
<pre>  archives/[archiveid]/cfg/lang/[langid]/static
 +
  archives/[archiveid]/cfg/static
 +
  archives/[archiveid]/themes/[themeid]/static
 +
  lib/themes/[themeid]/static
 +
  lib/lang/[langid]/static
 +
  lib/static</pre>
  
This function also sets the path in which the Parser will look for  DTD files to the repository's config directory.
+
<!-- Edit below this comment -->
  
Returns undef if an error occurs during parsing.
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=item_get_id -->==get_id==
+
<!-- Pod2Wiki=head_id -->
 +
===id===
  
  $id = $repository-&gt;get_id
+
<source lang="perl">$id = $repository->id
  
 +
</source>
 
Returns the id string of this repository.
 
Returns the id string of this repository.
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_exec -->==exec==
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_exec -->
 +
===exec===
  
  $returncode = $repository-&gt;exec( $cmd_id, %map )
+
<source lang="perl">$returncode = $repository->exec( $cmd_id, %map )
  
 +
</source>
 
Executes a system command. $cmd_id is the id of the command as set in SystemSettings and %map contains a list of things to "fill in the blanks" in the invocation line in SystemSettings.  
 
Executes a system command. $cmd_id is the id of the command as set in SystemSettings and %map contains a list of things to "fill in the blanks" in the invocation line in SystemSettings.  
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_invocation -->==invocation==
+
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_test_config -->
 +
===test_config===
 +
 
 +
<source lang="perl">( $returncode, $output) = $repository->test_config
 +
 
 +
</source>
 +
This runs "epadmin test" as an external script to test if the current configuraion on disk loads OK. This can be used by the web interface to test if changes to config. files may be saved, or not.
 +
 
 +
$returncode will be zero if everything seems OK.
 +
 
 +
If not, then $output will contain the output of epadmin test
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_reload_config -->
 +
===reload_config===
 +
 
 +
<source lang="perl">$ok = $repository->reload_config
 +
 
 +
</source>
 +
Trigger a configuration reload on the next request/index.
 +
 
 +
To reload the configuration right now just call [[API:EPrints/Repository#load_config|load_config]].
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_html_phrase -->
 +
===html_phrase===
 +
 
 +
<source lang="perl">$xhtml_phrase = $repository->html_phrase( $phraseid, %inserts )
 +
 
 +
</source>
 +
Return an XHTML DOM object describing a phrase from the phrase files.
 +
 
 +
$phraseid is the id of the phrase to return. If the same ID appears in both the repository-specific phrases file and the system phrases file then the repository-specific one is used.
 +
 
 +
If the phrase contains &lt;ep:pin&gt; elements, then each one should have an entry in %inserts where the key is the "ref" of the pin and the value is an XHTML DOM object describing what the pin should be  replaced with.
  
  $commandstring = $repository-&gt;invocation( $cmd_id, %map )
+
<!-- Edit below this comment -->
  
Finds the invocation for the specified command from SystemSetting and fills in the blanks using %map. Returns a string which may be executed as a system call.
 
  
All arguments are ESCAPED using quotemeta() before being used (i.e. don't pre-escape arguments in %map).
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_phrase -->
 +
===phrase===
  
<!-- End of Pod2Wiki -->
+
<source lang="perl">$utf8_text = $repository->phrase( $phraseid, %inserts )
<!-- Pod2Wiki=item_get_field_defaults -->==get_field_defaults==
 
  
  $defaults = $repository-&gt;get_field_defaults( $fieldtype )
+
</source>
 +
Performs the same function as html_phrase, but returns plain text.
  
Return the cached default properties for this metadata field type. or undef.
+
All HTML elements will be removed, &lt;br&gt; and &lt;p&gt; will be converted  into breaks in the text. &lt;img&gt; tags will be replaced with their  "alt" values.
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_set_field_defaults -->==set_field_defaults==
 
  
  $repository-&gt;set_field_defaults( $fieldtype, $defaults )
 
  
Cache the default properties for this metadata field type.
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_noise -->
 +
===noise===
  
<!-- End of Pod2Wiki -->
+
<source lang="perl">$noise_level = $repository->noise
<!-- Pod2Wiki=item_generate_dtd -->==generate_dtd==
 
  
  $success = $repository-&gt;generate_dtd
+
</source>
 +
Return the noise level for the current session. See the explaination under EPrints::Repository-&gt;new()
  
Regenerate the DTD file for each language. This file is used when loading some of the XML files. It contains entities such as &amp;ruler; and &amp;adminemail; which make maintaining the XML files easier.
+
<!-- Edit below this comment -->
  
The entites in the DTD file are configured by get_entities in the ArchiveConfig.pm module.
 
  
Returns true. Might return false on error (not checking yet).
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_plugins -->
 +
===plugins===
  
<!-- End of Pod2Wiki -->
+
<source lang="perl">@plugins = $repository->plugins( [ $params, ] %restrictions )
<!-- Pod2Wiki=item_test_config -->==test_config==
 
  
  ( $returncode, $output) = $repository-&gt;test_config
+
</source>
 +
Returns a list of plugin objects that conform to %restrictions (may be empty).
  
This runs "epadmin test" as an external script to test if the current configuraion on disk loads OK. This can be used by the web interface to test if changes to config. files may be saved, or not.
+
If $params is given uses that hash reference to initialise the plugins. Always passes this session to the plugin constructor method.
  
$returncode will be zero if everything seems OK.
+
<!-- Edit below this comment -->
  
If not, then $output will contain the output of epadmin test
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
+
<!-- Pod2Wiki=head_init_from_indexer -->
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
+
===init_from_indexer===
<!-- Pod2Wiki=item_can_execute -->==can_execute==
 
  
<!-- End of Pod2Wiki -->
+
<source lang="perl">$repo->init_from_indexer( $daemon )
<!-- Pod2Wiki=item_can_invoke -->==can_invoke==
 
  
<!-- End of Pod2Wiki -->
+
</source>
<!-- Pod2Wiki=item_check_secure_dirs -->==check_secure_dirs==
+
(Re)initialise the repository object for use by the indexer.
  
<!-- End of Pod2Wiki -->
+
Calls [[API:EPrints/Repository#check_last_changed|check_last_changed]].
<!-- Pod2Wiki=item_freshen_citation -->==freshen_citation==
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=head_copyright -->
<!-- Pod2Wiki=item_freshen_template -->==freshen_template==
+
==COPYRIGHT==
 +
Copyright 2000-2011 University of Southampton.
  
<!-- End of Pod2Wiki -->
+
This file is part of EPrints http://www.eprints.org/.
<!-- Pod2Wiki=item_get_citation_spec -->==get_citation_spec==
 
  
<!-- End of Pod2Wiki -->
+
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
<!-- Pod2Wiki=item_get_citation_type -->==get_citation_type==
 
  
<!-- End of Pod2Wiki -->
+
EPrints 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 Lesser General Public License for more details.
<!-- Pod2Wiki=item_get_plugin_class -->==get_plugin_class==
 
  
<!-- End of Pod2Wiki -->
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
<!-- Pod2Wiki=item_get_plugin_ids -->==get_plugin_ids==
 
  
<!-- End of Pod2Wiki -->
+
<!-- Edit below this comment -->
<!-- Pod2Wiki=item_get_workflow_config -->==get_workflow_config==
 
  
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new_archive_by_id -->==new_archive_by_id==
 
  
<!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->
+
<!-- Pod2Wiki=_postamble_ -->
 +
<!-- Edit below this comment -->

Latest revision as of 14:39, 30 July 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Repository - connection to a single repository instance


SYNOPSIS

use EPrints;

$repo = EPrints->new->current_repository;

$repo = EPrints->new->repository( "myrepo" );

$xml = $repo->xml;
$cuser = $repo->current_user;
$repo->log( "Got user " . $cuser->id );


DESCRIPTION

EPrints::Repository represents a connection to the EPrints system. It connects to a single EPrints repository, and the database used by that repository.

Each Repository has a "current language". If you are running in a multilingual mode, this is used by the HTML rendering functions to choose what language to return text in.

The Repository object also knows about the current apache connection, if there is one, including the CGI parameters.

If the connection requires a username and password then it can also give access to the EPrints::DataObj::User object representing the user who is causing this request. See current_user.

The Repository object provides access to the EPrints::XML and EPrints::XHTML class which contain methods for creating XHTML results which can be returned via the web interface.


METHODS

new

$repository = EPrints::Repository->new( %opts )

Creates and returns a new repository object. This is a utility object only and will only have the basic system configuration available.


new

$repository = EPrints::Repository->new( $repository_id, %opts )

Create a connection to an EPrints repository $repository_id which provides access to the database and to the repository configuration.

Options:

  db_connect - 1
  check_db - 1
  noise - 0


create_from_data

$repo = EPrints::Repository->create_from_data( $epdata )

Create a new repository instance using $epdata.


delete

$repo->delete()

Destroy the repository and all its contents.

To allow this method you must first set $EPrints::Repository::ALLOW_DELETE to 1.


query

$query = $repository->query

Return the CGI object describing the current HTTP query, or undefined if this isn't a CGI script.


url_param

$value or @values = $repository->url_param( $name )

Retrieve the UTF-8 value(s) of the query parameter $name for the current request.

This will not cause the POST data to be read.


param

$value or @values = $repository->param( $name )

Passes through to CGI.pm param method.

$value = $repository->param( $name ): returns the value of CGI parameter $name.

@values = $repository->param: returns an array of the names of all the CGI parameters in the current request.


xml

$xml = $repo->xml

Return an EPrints::XML object for working with XML.


xhtml

$xhtml = $repo->xhtml

Return an EPrints::XHTML object for working with XHTML.


eprint

$eprint = $repository->eprint( $eprint_id );

A convience method to return the EPrints::DataObj::EPrint with the given ID, or undef.

Equivent to $repository->dataset("eprint")->dataobj( $eprint_id )


current_language

$lang = $repository->current_language

Returns the current language.


current_user

$user = $repository->current_user

Return the current logged in EPrints::DataObj::User for this session.

Return undef if there isn't one.


user

$user = $repository->user( $user_id );

A convience method to return the EPrints::DataObj::User with the given ID, or undef.

Equivent to $repository->dataset("user")->dataobj( $user_id )


user_by_username

$user = $repository->user_by_username( $username );

Return the user with the given username, or undef.


user_by_email

$user = $repository->user_by_email( $email );

Return the EPrints::DataObj::User with the given email, or undef.


template

$template = $repository->template( [ $id ] )


dataset

$dataset = $repository->dataset( $setname )

Return a given EPrints::DataSet or undef if it doesn't exist.


config

$confitem = $repository->config( $key, [@subkeys] )

Returns a named configuration setting including those defined in archvies/<archive_id>/cfg/cfg.d/

$repository->config( "stuff", "en", "foo" )

is equivalent to

$repository->config( "stuff" )->{en}->{foo}


log

$repository->log( $msg [, $level ] )

Log a plain text message $msg. If $level is given only logs if $level is greater than or equal to noise.

To override where log messages are sent define the log callback:

  $c->{log} = sub {
    my( $repo, $msg, $level ) = @_;
  
    ...
  };


call

$result = $repository->call( $cmd, @params )

Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.


can_call

$boolean = $repository->can_call( @cmd_conf_path )

Return true if the given subroutine exists in this repository's config package.


try_call

$result = $repository->try_call( $cmd, @params )

Calls the subroutine named $cmd from the configuration perl modules for this repository with the given params and returns the result.

If the subroutine does not exist then quietly returns undef.

This is used to call deprecated callback subroutines.


template_dirs

@dirs = $repository->template_dirs( $langid )

Returns a list of directories from which template files may be sourced, where the first matching template encountered is used.

The directories searched are:

  archives/[archiveid]/cfg/lang/[langid]/templates/
  archives/[archiveid]/cfg/templates/
  archives/[archiveid]/cfg/themes/[themeid]/lang/[langid]/templates/
  archives/[archiveid]/cfg/themes/[themeid]/templates/
  lib/themes/[themeid]/templates/
  lib/lang/[langid]/templates/
  lib/templates/


get_static_dirs

@dirs = $repository->get_static_dirs( $langid )

Returns a list of directories from which static files may be sourced.

Directories are returned in order of importance, most important first:

  archives/[archiveid]/cfg/lang/[langid]/static
  archives/[archiveid]/cfg/static
  archives/[archiveid]/themes/[themeid]/static
  lib/themes/[themeid]/static
  lib/lang/[langid]/static
  lib/static


id

$id = $repository->id

Returns the id string of this repository.


exec

$returncode = $repository->exec( $cmd_id, %map )

Executes a system command. $cmd_id is the id of the command as set in SystemSettings and %map contains a list of things to "fill in the blanks" in the invocation line in SystemSettings.


test_config

( $returncode, $output) = $repository->test_config

This runs "epadmin test" as an external script to test if the current configuraion on disk loads OK. This can be used by the web interface to test if changes to config. files may be saved, or not.

$returncode will be zero if everything seems OK.

If not, then $output will contain the output of epadmin test


reload_config

$ok = $repository->reload_config

Trigger a configuration reload on the next request/index.

To reload the configuration right now just call load_config.


html_phrase

$xhtml_phrase = $repository->html_phrase( $phraseid, %inserts )

Return an XHTML DOM object describing a phrase from the phrase files.

$phraseid is the id of the phrase to return. If the same ID appears in both the repository-specific phrases file and the system phrases file then the repository-specific one is used.

If the phrase contains <ep:pin> elements, then each one should have an entry in %inserts where the key is the "ref" of the pin and the value is an XHTML DOM object describing what the pin should be replaced with.


phrase

$utf8_text = $repository->phrase( $phraseid, %inserts )

Performs the same function as html_phrase, but returns plain text.

All HTML elements will be removed, <br> and <p> will be converted into breaks in the text. <img> tags will be replaced with their "alt" values.


noise

$noise_level = $repository->noise

Return the noise level for the current session. See the explaination under EPrints::Repository->new()


plugins

@plugins = $repository->plugins( [ $params, ] %restrictions )

Returns a list of plugin objects that conform to %restrictions (may be empty).

If $params is given uses that hash reference to initialise the plugins. Always passes this session to the plugin constructor method.


init_from_indexer

$repo->init_from_indexer( $daemon )

(Re)initialise the repository object for use by the indexer.

Calls check_last_changed.

COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.