| XML::DB::Collection - A collection of data returned from the db. |
XML::DB::Collection - A collection of data returned from the db.
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 ($@);
}
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.
Graham Seaman
CPAN ID: GSEAMAN
graham@opencollector.org
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.
XML::DB::DatabaseManager, XML::DB::Resource.
Usage : $col->close()
Purpose : Releases all resources used by the Collection. Here simply sets a flag.
Argument : None
Returns : void
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
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
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
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
Usage : $name = $col->getName()
Purpose : Returns the name of this collection
Argument : None
Returns : String
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
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
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
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
I<Throws> : COLLECTION_CLOSED
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
Usage : if ($col->isOpen()){ ...
Purpose : Tests if Collection is open
Argument : None
Returns : Boolean
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
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
Usage : $col->removeResource($resource)
Purpose : Removes given resource from database
Argument : Resource
Returns : void
I<Throws> : COLLECTION_CLOSED, DRIVER_ERROR
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
Usage : $property = $col->getProperty($name)
Purpose : Returns named property
Argument : None
Returns : String or null
Usage : $col->setProperty($name, $value)
Purpose : Sets property to value
Argument : Name and value of property
I<Returns> : void
Usage : Never called directly by user (see synopsys for creation of Collections) Purpose : Constructor
| XML::DB::Collection - A collection of data returned from the db. |