Pawn:Workflow and Call Overview

Scheduler Configuration Operations (Scheduler)

setPassword(account, password)

addAdmin(account, pass)

Management Server

addProducer(issuerURL, serverURL, cert)

Add a producer with a namespace of issuerURL, contactable at serverURL, and will have clients present saml tokens signed by the private key corresponding to cert

removeProducer(issuerURL)

Remove producer by issuerURL

listProducers()

return string list of all registered managers by issuerURL

getProducerURL(issuerURL)

return the server location of issuerURL

setProducerURL(issuerURL, newServerURL)

set server url of a producer

setProducerCert(issuerURL, cert)

set certificate for producer

getProducerCert(issuerURL)

return string reprentation of cert for producer

CA management

addCACertificate(cert)

add new trusted, signing CA

removeCACertificate(dn)

remove trusted CA certificate by DN

listAuthorities()

return string list of trusted CA DN's

Resources

addResourceInstance(rsrcName, driver, issuer, domain, driverParameters[], clientParameters[])

add resource instance of name, driver is class to use for this resource, parameters are parameterBeans used to configure resource.

rsrcName - descriptive name for the resource

driver - name of factory class that identifies the driver

issuer - management server that is allowed to use this resource

domain - domain on the management server that is allowed. A blank domain means anyone on the management svr can use it.

driverParameters - parameters shipped to the receiving server driver

clientParameters - parameters given to the client to let it choose a final destination for a package

removeResourceInstance(rsrcName)

remove resource by name

istResourceInstances()

list names of available resources (used by receivers also)

getResourceDriverParameters(name)

return list of parameterBeans[] used to configure receiving server driver.

getResourceClientParameters(name)

return list of parameterBeans[] used to initialize client interface.

getResourceInstanceClass(name)

return name of class to be used as driver for resource

getResourceInstanceIssuer(name)

return name of management server this resource belongs to.

getResourceInstanceDomain(name)

return domain that owns this resource.

listResourceInstancesByDomain(issuerURL, domain)

list all resources that are accessable to the domain in the given management server. Used by client.

listResourceInstancesByProducer(issuerURL)

list all resources that are available to a management server. Used for configuration purposes only

Driver Config

addResourceDriver(driver, string[] fileList)

add the listed jars as requirements for the named driver. The driver name should be the name of the factory class that implements <nop>ResourceFactory. The files listed should be included as attachments to the call.

getResourceDriverJars(driver)

Return a list of jar files that power the listed driver. Jar files are returned as attachements to the response. The returned string array lists the names of the jar files.

listResourceDriverJars(driver)

Return string list of jar files that are part of this driver. This only lists the names, use getResourceDriverJars to retrieve the actual files.

listResourceDrivers()

return list of all available drivers.

removeResourceDriver(driver)

remove driver files and any registered configuration instances of that driver.

removeResourceDriverJar(driver, jarName)

remove a jar from list included in driver.

Receiving Server Config

listReceivingServers()

return string list of registered receiving servers

addReceivingServer(server, password, url)

add new receiving server w/ hostname server, password and accessable at url.

removeReceivingServer(server)

remove receiving server named server

setReceivingURL(server, url)

set url of receiving server

addReceivingPool(server, poolName, poolPath)

add new storage pool on server named poolName at path poolPath

removeReceivingPool(server, poolName)

remove pool from receiver, doesn't take affect until receiver reloads

getReceivingPoolList(server)

return list of receiving pool on a server

getReceivingURL(server)

return server url of a receiving server

getReceivingPoolPath(server, poolName)

return path of named storage pool on server

Receiver to Scheduler config retrievals (Scheduler)

getCACertificates()

return list of strings of the CA certificates

getProducerCertificates()

return string list of producer certificates

Receiver to Scheduler Updates (Scheduler)

removeReservationCache(server, reservation)

remove reservation ID from list of available reservations

addReservationCache(server, reservation)

add reservation located at server to cache

updateReservationCache(server, reservationIDs[])

bulk update reservation cache from server, used at bootup. This will clear all existing id's prior to setting.

updatePoolClassAd(server, pool, classad[])

update the classad used for allocating reservations to storage pools. parameterBean classad[] is the value/attr pairs for this classad.

Client to scheduler interactions. (Scheduler)

requestReservation(size, fileCount)

request new reservation w/ expected file count and total size. [[#SchedulerBean][schedulerBean]] describing where reservation was allocated is returned.

lookupReservation(reservationID)

look for a reservation in local cache

Scheduler to receiving server actions (Receiver)

This also includes items from the scheduler gui to receiving servers

Reservation Management

createReservation(reservationID, pool, client, domain, issuer)

Create reservation with a given ID in the named pool, owned by client in domain from management server specified by issuer

listReservations()

list reservations contained on server. Returns string list of ID's

listReservationsInPool(poolName)

list reservations for a given storage pool.

getReservationUser(r)

return user who owns reservation

getReservationDomain(r)

return domain owning this reservation

getReservationManager(r)

return management server url of owning manager.

removeReservation(r)

remove reservation from receiving server and update scheduler cache.

Client to receiving server interactions (Receiver)

This interaction requires a client to have a pre-existing reservation ID. Please note that obligation = category. Calls adhere to the rules of client level security.

Reservation Level

getStatus(r)

get current status of a reservation. Response codes are documented in edu.umiacs.pawn.shared.udt.PACKAGE.

BUSY - validation or other processing is occuring. Certain modifications may be blocked.

AVAILABLE - ready for modification, and last validation returned success.

ERROR - error report available, clear by making appropriate changes and re-running validation

REMOVED - for some reason a ghost of the reservation has remained.

getErrorReport(r)

If an error report exists, return is as a string.

validateReservation(r)

check reservation for completeness, including set roots for all obligations, referential integrity for all manifests and associated files. object integrity against checksums in manifests. During validation reservation state is BUSY, and if validation fails a report is set and state is set to ERROR. If successful, reservation is set to AVAILABLE.

listObligations(r)

returns an array of <nop>OligationBean describing available obligations. Description can be found [[#ObligationBean][here]]

===Create Category / Obligation=== (r = reservation ID, o = obligation ID)

createObligation(r,o)

Create a new obligation of category in a reservation. The ID should be an ID that is meaningful to the management server, not necessarily descriptive

setObligationDescription(r,o, description)

Set the description on an Obligation or Category. Can be called anytime after createObligation. This is optional.

getObligationDescription(r,o)

Return any description that was set.

removeObligation(r,o)

Remove an obligation and all manifests and data under it. Use with caution.

Object Actions (require pre-existing manifest, m = manifest identifier)

fileInformation is an array of FileBean described here. The call must also have attachements (Soap w/ Attachments) that correspond to each item in the fileInformation array. This will return a list of files that have failed ingestion.

retrieveObjects(r,o, m,objectList[])

Download a given list of objects from a manifest. Returned files will be returned as attachments. The call will return a string list corresponding to the attachments.

listObjects(r,o,m)

List all objects associated with a given manifest.

removeObject(r,o,m,objectURN)

Remove object specified by objectURN

Compound Object Description

SchedulerBean field description

Date date

date reservation is valid

String authority

domain of user

String client

username of client using this reservation (receiving server)

String receivingServer

url of receiving server housing reservation (client)

String reservationID

id of this reservation

String managerURL

url to callback manager (receiving server) - should be deprecated

String receivingPool

pool name where reservation exists (receiving server)

String issuer

issuer url (receiving server)

ParameterBean field description

String key

key for this parameter

String value

value for this parameter

ObligationBean field description

String description

description from setObligationDescription

String name

name of obligation given upon creation.

String rootURN

current root manifest

FileBean field description

String checksum

value of checksum

String checksumType

type of checksum, this should be the string that is known to java crypto. (ie, SHA-1, MD5, etc).

String fileName

identifier of ingested file. This corresponds to the flocat, metadataReference, metsPointer in mets identified by 'xlink:role="urn:pawn:client" LOCTYPE="URN"' for data, metadata, or child mets documents.

Call Security

Standard client-level security - client - receiving server

Access to call is allowed if any of the following are met:

• saml token is issued by scheduler and role is scheduler
• saml token issuer = reservation.issuer, and role is client, and client = reservation.client and domain = reservation.domain
• saml token issuer = reservation.issuer, and role is manager, and domain = reservation.domain
• saml token issuer = reservation.issuer, and role is admin

-- Main.MikeSmorul - 26 Jan 2006