NAME

XML::DB::Collection - A collection of data returned from the db.

SYNOPSIS

eval{ $dbm = new XML::DB::DatabaseManager(); $dbm->registerDatabase($driver); $col = $dbm->getCollection("xmldb:$driver:$url/db/test"); };

if ($@){ die $@; }

$name = $col->getName();

if ($col->isOpen()){ # always true unless explicitly closed eval{ $count = $col->getChildCollectionCount(); $list_ref = $col->listChildCollections(); $child_collection = $col->getChildCollection($child_name); $parentCollection = $col->getParentCollection();

	$new_id = $col->createId();
	$new_resource = $col->createResource($new_id, 'XMLResource');
	$col->storeResource($new_resource);
	$col->removeResource($resource);
	
	$resources = $col->getResourceCount();
	$resource = $col->getResource($id);
	
	$list_ref = $col->getServices();
	$service = $col->getService('XPathQueryService', '1.0');
	
	$col->setProperty($name, $value);
	$property = $col->getProperty($name);
	
	$col->close();
    };
    die $@ if ($@);
}

DESCRIPTION

This class implements the interface Collection from the XML:DB base specification. The initial Collection must be obtained from the DatabaseManager; after that, Collections can also be obtained from the CollectionManager service or from the initial Collection itself.

Collections are hierarchical, with a parent and possibly children. The Collection is the main route to access actual documents in the database: it provides access to Resources (which are abstractions of documents or document fragments) and Services (XPath queries, XUpdate commands, and the CollectionManager service). A collection is an analog to a table in a relational DB, or a directory in a file-system.

AUTHOR

Graham Seaman
CPAN ID: GSEAMAN
graham@opencollector.org

COPYRIGHT

Copyright (c) 2002 Graham Seaman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

XML::DB::DatabaseManager, XML::DB::Resource.

PUBLIC METHODS

close

Usage : $col->close()

Purpose : Releases all resources used by the Collection. Here simply sets a flag.

Argument : None

Returns : void

createId

Usage : $newId = $col->createId()

Purpose : Creates a new ID unique within the context of the Collection

Argument : None

Returns : new ID string

Throws : DRIVER_ERROR, COLLECTION_CLOSED

createResource

Usage : $resource = $col->createResource($id, $type)

Purpose : Creates a new empty Resource with the provided id.

Argument : Type may be 'XMLresource' or 'BinaryResource'. The id must be unique for the collection; if null, a new id will be generated.

Returns : Resource

Comments : BinaryResource not implemented

Throws : COLLECTION_CLOSED

getChildCollection

Usage : $collection = $col->getChildCollection($name)

Purpose : Returns a Collection for the named child collection

Argument : None

Returns : Collection or null

Throws : COLLECTION_CLOSED, DRIVER_ERROR

getChildCollectionCount

Usage : $no = $col->getChildCollectionCount()

Purpose : Returns the number of collections under this collection (may be 0)

Argument : None

Returns : Number

Throws : COLLECTION_CLOSED, DRIVER_ERROR

getName

Usage : $name = $col->getName()

Purpose : Returns the name of this collection

Argument : None

Returns : String

getParentCollection

Usage : $parentCollection = $col->getParentCollection()

Purpose : Returns the parent of this collection (undef if none)

Argument : None

Returns : Collection or undef

Throws : COLLECTION_CLOSED, DRIVER_ERROR

getResource

Usage : $resource = $col->getResource($id)

Purpose : Returns the resource with the given id from the database

Argument : $id

Returns : Resource or null

Throws : COLLECTION_CLOSED

getResourceCount

Usage : $no = $col->getResourceCount()

Purpose : Returns the number of resources currently stored in the collection or zero if empty

Argument : None

Returns : Number

Throws : COLLECTION_CLOSED, DRIVER_ERROR

getService

Usage : $service = $col->getService($name, $version)

Purpose : Returns the Service with the given name and version

Argument : Name of service and version (currently always 1.0)

Returns : Service or null if does not exist

Throws : COLLECTION_CLOSED

getServices

Usage : $list = $col->getServices()

Purpose : Returns a list of names of services known to the Collection

Argument : None

Returns : Array of strings (may be empty)

Throws : COLLECTION_CLOSED

isOpen

Usage : if ($col->isOpen()){ ...

Purpose : Tests if Collection is open

Argument : None

Returns : Boolean

listChildCollections

Usage : $list = $col->listChildCollections()

Purpose : Returns a list of names of children of this collection

Argument : None

Returns : Array of strings (may be empty)

Throws : COLLECTION_CLOSED, DRIVER_ERROR

listResources

Usage : $list = $col->listResources()

Purpose : Returns a list of ids of all resources in the Collection

Argument : None

Returns : Array of strings

Throws : COLLECTION_CLOSED, DRIVER_ERROR

removeResource

Usage : $col->removeResource($resource)

Purpose : Removes given resource from database

Argument : Resource

Returns : void

Throws : COLLECTION_CLOSED, DRIVER_ERROR

storeResource

Usage : $col->storeResource($resource)

Purpose : Stores resource in database. Updates the resource if it already exists.

Argument : Resource

Returns : void

Throws : COLLECTION_CLOSED, DRIVER_ERROR

getProperty

Usage : $property = $col->getProperty($name)

Purpose : Returns named property

Argument : None

Returns : String or null

setProperty

Usage : $col->setProperty($name, $value)

Purpose : Sets property to value

Argument : Name and value of property

Returns : void

new

Usage : Never called directly by user (see synopsys for creation of Collections)

Purpose : Constructor

cpanm XML::DB::Service

perl -MCPAN -e shell
install XML::DB::Service