16. Werken met Docman

Auteur Richard Philips
Aanmaak 12 april 2006
Oud BVV nr 2120

16.1. Abstract

Dit document beschrijft het gebruik van Docman.

16.2. Inleiding

Docman is een geheel van software tools om een grote collectie bestanden te beheren. Deze bestanden kunnen dan op een eenvoudige wijze - bijvoorbeeld via URLs - in Brocade applicaties worden gebruikt.

Docman komt in 3 verschillende smaken:

  • de toolcat software: docman
  • een python API
  • een aantal mumps macro’s

16.3. Soorten bestanden

Er zijn twee manieren waarop we Docman bestanden kunnen indelen:

  • naargelang de levensduur van het bestand
  • naargelang de terugvindbaarheid

In Docman kan - bij het opslaan van een bestand - worden aangegeven wanneer het bestand moet afsterven (de murderdate). Het feit of een bestand eeuwig moet bestaan of niet is een eerste opdeling van de docman bestanden.

Soms kan men op basis van een URL voorspellen wat een andere, gelijkaardige, URL is en dit is niet altijd toegelaten. Zo is bijvoorbeeld in Impala een electronisch document steeds gekoppeld aan het impala nummer. Men mag dan niet zomaar op basis van de URL gaan uitmaken wat de URL is van het document bij het vorige impala nummer. Deze eigenschap kan ook overbodig zijn. Het eerste soort bestanden noemen we hidden.

16.4. Docman databases

Docman bestanden worden gegroepeerd in Docman databases. Deze zijn applicatie georiënteerd. Zo zijn er Docman databases voor Impala, Hyperlib, Kahawa, STCV, Virlib, Procman, ...

Met behulp van de Docman toolcat applicatie kunnen deze databanken eenvoudig worden gemanipuleerd:

Creatie van een docman databank docman -db create <name>
Listen van alle databanken docman -db list
Schrappen van een databank (incl. alle bestanden!) docman -db delete <name>
Schrappen van verouderde bestanden docman -db murder <name>

Docman databases worden zelden aangemaakt. De meest geëigende plaats om zo’n databank aan te maken is in release.py van een passend project:

from anet.core import installer
installer.docman(<name>)

16.5. Docman paths

Een Docman path is een unieke identificatie van een bestand binnen Docman.

Er zijn 3 verschillende vormen die een Docman path kan aannemen.

Oude vorm exchange.98.90.bcprint7789.txt.rm20310713.19420.31305 Deze vorm wordt gekenmerkt door de exact 7 . die in het path voorkomen.
Hidden path /exchange/514847/bcprint5086.txt Deze vorm wordt gekenmerkt door de exact 3 / die in het path voorkomen.
Visible path /exchange/bcprint5086.txt Deze vorm wordt gekenmerkt door de exact 2 / die in het path voorkomen.

16.5.1. De eigenschappen van een Docman path

File

API
from anet.docman import docbase
print docbase.DocmanFile(<path>).file
Toocat docman -path list <path>

Docman bestanden worden in een filesysteem opgeslagen. Ze zijn dus bereikbaar via een klassieke filenaam van binnen het operating system.

URL

API
from anet.docman import docbase
print docbase.DocmanFile(<path>).url
Toocat docman -path list <path>
Mumps m4_docmanPath2URL

De URL is een absolute-path reference. Het Apache rewriting systeem zorgt ervoor dat de URLs goed worden opgelost.

size

API
from anet.docman import docbase
print docbase.DocmanFile(<path>).size

basename

API
from anet.docman import docbase
print docbase.DocmanFile(<path>).basename

murderdate

API
from anet.docman import docbase
print docbase.DocmanFile(<path>).murderdate

Indien het bestand eeuwig leeft, is de murderdate: None.

16.5.2. Voorbeeld 1

path = exchange.98.90.bcprint7789.txt.rm20310713.19420.31305

Eigenschap Waarde
from anet.docman import docbase
docbase.DocmanFile(<path>).file
/library/database/docman/exchange/98/90
/exchange.98.90.bcprint7789.txt.rm20310713.19420.31305
from anet.docman import docbase
docbase.DocmanFile(<path>).url
/docman/exchange
/exchange.98.90.bcprint7789.txt.rm20310713.19420.31305
from anet.docman import docbase
docbase.DocmanFile(<path>).basename
bcprint7789.txt
from anet.docman import docbase
docbase.DocmanFile(<path>).murderdate
2031-07-13

16.5.3. Voorbeeld 2

path = /exchange/514847/bcprint5086.txt

Eigenschap Waarde
from anet.docman import docbase
docbase.DocmanFile(<path>).file
/library/database/docman/exchange/x514/847
/bcprint5086.txt.rm20060721
from anet.docman import docbase
docbase.DocmanFile(<path>).url
/docman/exchange/514847/bcprint5086.txt
from anet.docman import docbase
docbase.DocmanFile(<path>).basename
bcprint5086.txt
from anet.docman import docbase
docbase.DocmanFile(<path>).murderdate
2006-07-21

16.5.4. Voorbeeld 3

path = /exchange/bcprint7789.txt

Eigenschap Waarde
from anet.docman import docbase
docbase.DocmanFile(<path>).file
/library/database/docman/exchange/98e/046
/bcprint7789.txt.rm20061029
from anet.docman import docbase
docbase.DocmanFile(<path>).url
/docman/exchange/bcprint7789.txt
from anet.docman import docbase
docbase.DocmanFile(<path>).basename
bcprint7789.txt
from anet.docman import docbase
docbase.DocmanFile(<path>).murderdate
2006-10-29

16.6. Best practises

De belangrijkste raad is wel dat je enkel het Docman path bijhoudt: met de API en de m4 kan je steeds het belangrijkste element (de URL) afleiden.

16.6.1. Hoe een bestand weg te schrijven in een Docman database?

API

Vorm 1: murderdate = YYYYMMDD

from anet.docman import docbase

docmanfile = docbase.store("/anet/tmp/antilope.xml", db="exchange", hidden=True, murderdate="20060725")
print docmanfile.path
print docmanfile.url

Vorm 2: murderdate = datetime.date(Y, M, D)

import datetime
from anet.docman import docbase

docmanfile = docbase.store("/anet/tmp/antilope.xml", db="exchange", hidden=True, murderdate=datetime.date(2006, 7, 25))
print docmanfile.path
print docmanfile.url

Vorm 3: murderdate = N (days alive)

from anet.docman import docbase

docmanfile = docbase.store("/anet/tmp/antilope.xml", db="exchange", hidden=True, murderdate=10)
print docmanfile.path
print docmanfile.url

toolcat

docman -store /anet/tmp/antilope.xml db=exchange hidden=yes murder=20060725

mumps

m4_docmanPath($path=RDpath, $filename="/anet/tmp/antilope.xml", $db="exchange", $liveuntil="20060725")
m4_docmanURL($url=RDurl, $filename="/anet/tmp/antilope.xml", $db="exchange", $liveuntil="20060725")

16.6.2. Hoe data uit een open fileobject wegschrijven naar een Docman database?

API

from anet.docman import docbase

docmanfile = docbase.storefileobj(f, name="antilope.xml", db="exchange", hidden=True, murderdate="20060725")
print docmanfile.url

toolcat

docman -store db=exchange hidden=yes murder=20060725 name=antilope.xml

mumps

/

16.6.3. Hoe een fileslot reserveren in een Docman database?

API

from anet.docman import docbase

docmanfile = docbase.slot(name="antilope.xml", db="exchange", hidden=True, murderdate="20060725")
print docmanfile.url

toolcat

docman -store db=exchange hidden=yes murder=20060725 name=antilope.xml slot=yes

mumps

/

16.6.4. Hoe een URL afleiden uit een Docman path?

API

from anet.docman import docbase

print docbase.DocmanFile("/exchange/e123a22/antilope.xml").url

toolcat

/

mumps

m4_docmanPath2URL($url=RDurl, $path="/exchange/e123a22/antilope.xml")