API:EPrints/DataObj
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
- 1 NAME
- 2 DESCRIPTION
- 3 CORE METADATA FIELDS
- 4 REFERENCES AND RELATED OBJECTS
- 5 INSTANCE VARIABLES
- 6 METHODS
- 6.1 Constructor Methods
- 6.2 Class Methods
- 6.3 Object Methods
- 6.3.1 clone
- 6.3.2 create_subdataobj
- 6.3.3 local_path
- 6.3.4 update_triggers
- 6.3.5 delete
- 6.3.6 empty
- 6.3.7 update
- 6.3.8 set_under_construction
- 6.3.9 under_construction
- 6.3.10 clear_changed
- 6.3.11 clear_citationcaches
- 6.3.12 commit
- 6.3.13 value
- 6.3.14 set_value
- 6.3.15 set_value_raw
- 6.3.16 get_values
- 6.3.17 repository
- 6.3.18 get_data
- 6.3.19 get_dataset
- 6.3.20 is_set
- 6.3.21 exists_and_set
- 6.3.22 id
- 6.3.23 get_gid
- 6.3.24 get_datestamp
- 6.3.25 render_value
- 6.3.26 render_citation
- 6.3.27 render_citation_link
- 6.3.28 render_citation_link
- 6.3.29 render_description
- 6.3.30 render
- 6.3.31 render_full
- 6.3.32 render_export_links
- 6.3.33 render_export_bar
- 6.3.34 uri
- 6.3.35 internal_uri
- 6.3.36 path
- 6.3.37 url
- 6.3.38 get_control_url
- 6.3.39 get_type
- 6.3.40 to_xml
- 6.3.41 to_sax
- 6.3.42 export
- 6.3.43 queue_changes
- 6.3.44 queue_all
- 6.3.45 queue_fulltext
- 6.3.46 queue_removed
- 6.3.47 has_owner
- 6.3.48 permit
- 6.3.49 in_editorial_scope_of
- 6.3.50 validate
- 6.3.51 get_warnings
- 6.3.52 validate_field
- 6.3.53 tidy
- 6.3.54 add_stored_file
- 6.3.55 stored_file
- 6.3.56 add_dataobj_relations
- 6.3.57 has_dataobj_relations
- 6.3.58 has_related_dataobjs
- 6.3.59 related_dataobjs
- 6.3.60 remove_dataobj_relations
- 7 SEE ALSO
- 8 COPYRIGHT
NAME
EPrints::DataObj - Base class for records in EPrints.
DESCRIPTION
This is a base class that is inherited by EPrints::DataObj::EPrint, EPrints::DataObj::User, EPrints::DataObj::Subject and EPrints::DataObj::Document and various other classes representing data objects.
This class is abstract and its methods should not be called directly.
Synopsis
$dataobj = $dataset->dataobj( $id ); $dataobj->delete; $dataobj->commit( $force ); $dataset = $dataobj->dataset; $repo = $dataobj->repository; $id = $dataobj->id; $dataobj->set_value( $fieldname, $value ); $value = $dataobj->value( $fieldname ); \@value = $dataobj->value( $fieldname ); # multiple $boolean = $dataobj->is_set( $fieldname ); $xhtml = $dataobj->render_value( $fieldname ); $xhtml = $dataobj->render_citation( $style, %opts ); $uri = $dataobj->uri; $string = $dataobj->export( $plugin_id, %opts ); $dataobj = $dataobj->create_subobject( $fieldname, $epdata );
CORE METADATA FIELDS
None. This is an abstract class from which real data objects inherit and then add their metadata fields.
REFERENCES AND RELATED OBJECTS
None. This is an abstract class from which real data objects inherit and then add their references and related objects.
INSTANCE VARIABLES
$self->{changed}
A reference to a hash containing the old values of metadata that has changed since his the data object was last committed.
$self->{data}
A reference to a hash containing the metadata of this record.
$self->{dataset}
The EPrints::DataSet to which this record belongs.
$self->{non_volatile_change}
A boolean signifying whether the current changes include at least one change to a non-volatile field.
$self->{session}
The current EPrints::Repository. This use to be EPrints::Session but was replaced in later versions. See EPrints::BackCompatibility.
$self->{under_construction}
A boolean signifying if the data object is currently under construction and therefore know house-keeping should be carried out on the data object whilst set.
METHODS
Constructor Methods
new
$dataobj = EPrints::DataObj->new( $session, $id, [ $dataset ] )
Return new data object, created by loading it from the database.
If $dataset is not defined uses the default dataset for this object.
new_from_data
$dataobj = EPrints::DataObj->new_from_data( $session, $data, [ $dataset ] )
Construct and and returns a new data object based on the $data hash reference of metadata.
This is usually called by create_from_data to ensure default values are set for those field values not initially included in $data before this method constructs the data object.
$dataset is determined from the class if not provided.
create
$dataobj = EPrints::DataObj::create( $session, @default_data )
ABSTRACT
Create a new object of this type in the database.
The syntax for @default_data depends on the type of data object.
create_from_data
$dataobj = EPrints::DataObj->create_from_data( $session, $data, [ $dataset ] )
Creates and returns a new data object of this type in the database.
$data is a structured hash reference with multiple dimensions to encompass compound, multiple and sub-object field values.
$dataset is the dataset to which the new data object will belong. If this is not defined, it is determined from the class.
This will pull in defaults for unset field values in $data before calling new_from_data. It will also create any sub-objects as well as the main object.
Call this via:
$dataset->create_object( $session, $data )
Class Methods
get_system_field_info
$sys_fields = EPrints::DataObj->get_system_field_info
Return an array describing the system metadata of the this dataset.
get_defaults
$defaults = EPrints::DataObj->get_defaults( $session, $data, [ $dataset ] )
Return default values for this object based on the starting $data. Uses the data object class to determine dataset if $dataset not set.
Should be subclassed.
get_dataset_id
$dataset = EPrints::DataObj->get_dataset_id
Returns the ID of the EPrints::DataSet object to which this record belongs.
xml_to_epdata
$epdata = EPrints::DataObj->xml_to_epdata( $session, $xml, %opts )
Populates $epdata based on $xml using options in %opts. This is the inverse of to_xml but doesn't create a new object.
export_fieldlist
EPrints::DataObj->export_fieldlist
Returns fields to be exported by plugins that do not have pre-defined fields to export, (e.g. Export::XML).
in_export_fieldlist
EPrints::DataObj->in_export_fieldlist
Returns whether a field is in the export fieldlist for a particular data object. Returns true if there is no fieldlist restriction.
start_element
EPrints::DataObj->start_element( $data, $epdata, $state )
Consumes a SAX event.
$data is the SAX node data.
$epdata is an EPrints data structure to write values to.
$state maintains state between SAX calls but must contain at least:
dataset - the dataset the class belongs to
end_element
EPrints::DataObj->end_element( $data, $epdata, $state )
Ends element from start_element.
characters
EPrints::DataObj->characters( $data, $epdata, $state )
Consumes characters within start_element.
Object Methods
clone
$clone = $dataobj->clone
Clone the current data object, by creating a new data object of the same type and metadata but a new ID.
create_subdataobj
$subdataobj = $dataobj->create_subdataobj( $fieldname, $epdata )
Creates and returns a new data object that is a sub-object of this object in field $fieldname with initial data $epdata.
Clears the sub-object cache for this $fieldname which is equivalent to:
$dataobj->set_value( $fieldname, undef );
local_path
$local_path = $dataobj->local_path
Return local_path string for the history of the data object.
Should be subclassed.
update_triggers
$dataobj->update_triggers
Update all the stuff that needs to be updated before the data object is written to the database.
delete
$success = $dataobj->delete
Delete this data object from the database and any sub-objects or related files.
Alias for:
$dataobj->remove
Return true if successful.
empty
$dataobj->empty
Remove all of this object's values that may be imported.
update
$dataobj->update( $epdata [, %opts ] )
Update this object's values from $epdata. Ignores any values that do not exist in the dataset or do not have the 'import' property set.
include_subdataobjs - replace sub-dataobjs if given
# replaces all documents in $dataobj
$dataobj->update( {
title => "Wombats on Fire",
documents => [{
main => "wombat.pdf",
...
}],
}, include_subdataobjs => 1 );
set_under_construction
$dataobj->set_under_construction( $boolean )
Set a flag to indicate this object is being constructed and any house keeping will be handled by the method constructing it so don't do it elsewhere.
under_construction
$boolean = $dataobj->under_construction
Returns c<true> if this object is part way through being constructed.
clear_changed
$dataobj->clear_changed
Clear any changed fields, which will result in them not being committed unless force is used.
This method is used by the EPrints::Database to avoid unnecessary commits.
clear_citationcaches
$dataobj->clear_citationcaches
Clear any EPrints::DataObj::CitationCache objects associated with the data object.
commit
$success = $dataobj->commit( [ $force ] )
Write this object to the database and reset the changed fields.
If $force isn't true then it only actually modifies the database if one or more fields have been changed.
Commit may also queue indexer jobs or log changes, depending on the object.
value
$value = $dataobj->value( $fieldname )
Get a the value of a metadata field with $fieldname. If the field is not set then it returns undef unless the field has the property multiple set, in which case it returns [] (a reference to an empty a rray).
Alias for:
$dataobj->get_value( $fieldname )
set_value
$dataobj->set_value( $fieldname, $value )
Set the $value of the named metadata field $fieldname for this data object.
set_value_raw
$dataobj->set_value_raw( $fieldname, $value )
Set the $value of the named metadata field $fieldname for this data object by directly modifying its data hash reference. Use with care!
get_values
@values = $dataobj->get_values( $fieldnames )
Returns a list of all the values in this record of all the $fields specified by $fieldnames. These should be in the format used by browse views, using / to seperate individual field names with an optional .id suffix to indicate the ID part rather than the main part.
E.g. author.id/editor.id would return a list of all author and editor IDs from this record.
repository
$session = $dataobj->repository
Returns the EPrints::Repository object to which this record belongs.
Alias for:
$dataobj->get_session
get_data
$data = $dataobj->get_data
Returns a reference to the hash of all the metadata for this record keyed by fieldname.
get_dataset
$dataset = $dataobj->get_dataset
Returns the EPrints::DataSet object to which this record belongs.
is_set
$boolean = $dataobj->is_set( $fieldname )
Returns true if the field with $fieldname is set in this record, otherwise false.
Warns if the field with $fieldname does not exist.
exists_and_set
$boolean = $dataobj->exists_and_set( $fieldname )
Returns true if the field with $fieldname is set in this record, otherwise false.
If the field does not exist, just return false.
This method is useful for plugins which may operate on multiple repositories, when field not existing is not an issue for a particular repository.
id
$id = $dataobj->id
Returns the value of the primary key of this record.
Alias for:
$dataobj->get_id
get_gid
$gid = $dataobj->get_gid
DEPRECATED (see uri)
Returns the globally referential fully-qualified identifier for this data object or undef if this object can not be externally referenced.
get_datestamp
$datestamp = $dataobj->get_datestamp
Returns the datestamp of this object in "YYYY-MM-DD hh:mm:ss" format.
render_value
$xhtml = $dataobj->render_value( $fieldname, [ $showall ] )
Returns the rendered version of the value of the given $fieldname as appropriate for the current session. If $showall is true then all values are rendered - this is usually used for staff viewing data.
render_citation
$xhtml = $dataobj->render_citation( [ $style, %params ] )
Renders the record as a citation. If $style is set then it uses that citation style from the citations config file. Otherwise $style defaults to the type of this record. If $params{url} is set then the citation will link to the specified URL.
If $style is unset then use default.
render_citation_link
$xhtml = $dataobj->render_citation_link( [ $style, %params ] )
Renders a citation as like render_citation but as a link to the URL for this item. E.g. the abstract page of an eprint.
$params{url} is set to data object's URL if not set.
render_citation_link
$xhtml = $dataobj->render_citation_link( [ $style, %params ] )
Renders a citation as like render_citation but as a link to the control URL for this item. E.g. for items that are not yet in the live archive.
render_description
$xhtml = $dataobj->render_description
Returns a short description of this object using the brief citation style for this dataset or the default citation style of the former does not exist.
render
( $xhtml, $title ) = $dataobj->render
Return a chunk of XHTML DOM describing this object in the normal way. This is the public view of the record, not the staff view.
render_full
$xhtml = $dataobj->render_full
Return an XHTML table in DOM describing this record. All values of all fields are listed. This is the staff view.
render_export_links
$xhtml_ul_list = $dataobj->render_export_links( [ $staff ] )
Return a <ul> list containing links to all the formats this eprint is available in.
If $staff is true then show all formats available to staff and link to the staff export URL.
render_export_bar
$xhtml = $dataobj->render_export_bar( [ $staff ] )
Returns a rendered drop-down list of exports.
If $staff is true then include both public and staff visible export options.
uri
$url = $dataobj->uri
Returns a unique URI for this object. Not certain to resolve as a URL.
If $c-{dataobj_uri}->{eprint}> is a function, call that to work it out.
internal_uri
$uri = $dataobj->internal_uri
Return an internal URI for this object (independent of repository hostname).
To retrieve an object by internal URI use EPrints::DataSet::get_object_from_uri().
path
$path = $dataobj->path
Returns the relative path to this object from the repository's base URL, if the object has a URL.
Does not include any leading slash.
url
$url = $dataobj->url
Returns the URL for this record, e.g.the URL of the abstract page of an eprint.
Alias for:
$dataobj->get_url
get_control_url
$url = $dataobj->get_control_url
Returns the URL for the control page for this object.
get_type
$type = $dataobj->get_type
ABSTRACT.
Returns the type of this data object. This not the dataset it belongs to but the specific type within the dataset (e.g. c<user> could be editor, admin, etc.).
to_xml
$xmlfragment = $dataobj->to_xml( %opts )
Convert this object into an XML fragment using options %opts.
Options:
no_xmlns - Do not include a xmlns attribute in the outer element. (This assumes this chunk appears in a larger tree where the xmlns is already set correctly. showempty - Fields with no value are shown. embed - Include the data of a file, not just it's URL.
to_sax
$dataobj->to_sax( %opts )
Stream this object to a SAX handler using the options in $opts.
Options:
Handler - the SAX handler to build the output. revision_generation - Generate XML for revision files rather than export.
This does not output any document-level events.
export
$plugin_output = $dataobj->export( $plugin_id, %params )
Apply an export plugin with $plugin_id to this data object, using the parameters provided by %params and supplying them to the output_dataobj method of the EPrints::Plugin:Export plugin.
Return the output of the export plugin.
queue_changes
$dataobj->queue_changes
Add all the changed fields into the indexers todo queue.
queue_all
$dataobj->queue_all
Add all the fields into the indexers todo queue.
queue_fulltext
$dataobj->queue_fulltext
Add a fulltext index into the indexers todo queue.
queue_removed
$dataobj->queue_removed
Add an index removed event to the indexer's queue.
has_owner
$boolean = $dataobj->has_owner( $user )
Return true if $user owns this record. Normally this means they created it, but a group of users could count as owners of the same record if you wanted.
It's false on most data objects, except those which override this method.
permit
$rc = $dataobj->permit( $priv, [ $user ] )
# current user can edit via editorial role
if( $dataobj->permit( "xxx/edit", $user ) & 8 )
{
...
}
# anyone can view this object
if( $dataobj->permit( "xxx/view" ) )
{
}
Returns true if the specified $user (or 'anybody') can perform this action.
Returns a bit mask where:
0 - not permitted 1 - anybody 2 - logged in user 4 - user as owner 8 - user as editor
See also EPrints::Repository/allow_anybody and EPrints::DataObj::User/allow.
in_editorial_scope_of
$boolean = $dataobj->in_editorial_scope_of( $user )
As for has_owner, but if the $user is identified as someone with an editorial scope which includes this record.
Defaults to true. Which doesn't mean that they have the right to edit it, just that their scope matches. You also need editor rights to use this. It's currently used just to filter eprint editors so that only ones with appropriate scope and privilege can edit.
validate
$problems = $dataobj->validate( $for_archive )
Validate this data object. Not used on all sub-classed. $for_archive being true indicates that the item is beting validated to go live.
Returns a reference to an array of XHTML DOM objects describing validation problems with the entire data object for the supplied $for_archive archive ID.
A reference to an empty array indicates no problems.
get_warnings
$warnings = $dataobj->get_warnings
Returns a reference to an array of XHTML DOM objects describing problems with the entire data object.
A reference to an empty array indicates no problems.
validate_field
@problems = $dataobj->validate_field( $fieldname )
Check if a field named $fieldname is valid.
Returns a reference to an array of XHTML problems.
A reference to an empty array indicates no problems.
tidy
$dataobj->tidy
Cleans up any multiple fields with gaps.
add_stored_file
$file = $dataobj->add_stored_file( $filename, $filehandle, $filesize )
Convenience method to add (or replace) the file record for $filename to this object. Reads $filesize bytes from $filehandle.
Returns the file object or undef if the storage failed.
stored_file
$file = $dataobj->stored_file( $filename )
Get the file object for $filename.
Returns the file object or undef if the file doesn't exist.
Has alias:
$dataobj->get_stored_file( $filename )
add_dataobj_relations
$dataobj->add_dataobj_relations( $target, %relations )
Add a relation from this data object to the $target data object using predicates defined in the keys of the %relations hash. If values are defined in the hash reciprocal relationships from the $target data object to this data object are also.
You must commit $target data object after calling this method.
Has alias:
$dataobj->add_object_relations( $target, %relations )
has_dataobj_relations
$boolean = $dataobj->has_dataobj_relations( $target, @required )
Returns true if this object is related to $target by all @required.
If @required is empty will return true if any relationships exist.
Has alias:
$dataobj->has_object_relations( $target, @required )
$boolean = $dataobj->has_related_dataobjs( @required )
Returns true if related_dataobjs would return some objects but without actually retrieving the related objects from the database.
Has alias:
$dataobj->has_related_objects( @required )
@dataobjs = $dataobj->related_dataobjs( @required )
Returns a list of objects related to this data object by a relation in @required.
Has alias:
$dataobj->get_related_objects( @required )
remove_dataobj_relations
$dataobj->remove_dataobj_relations( $target, %relations )
Remove relations between this data object and the $target data object. If %relations is not empty only remove those relationships which are keys in this hash.
You must commit this object and $target to write the changes.
Has alias:
$dataobj->remove_object_relations( $target, %relations )
SEE ALSO
COPYRIGHT
© Copyright 2000-2024 University of Southampton.
EPrints 3.4 is supplied by EPrints Services.
http://www.eprints.org/eprints-3.4/
LICENSE
This file is part of EPrints 3.4 http://www.eprints.org/.
EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.
EPrints 3.4 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 3.4. If not, see http://www.gnu.org/licenses/.
