experimentDsApi.py

#!/usr/bin/env python

import os
import urllib

from dm.common.utility.encoder import Encoder
from dm.common.exceptions.dmException import DmException
from dm.common.objects.experiment import Experiment
from dm.common.objects.experimentType import ExperimentType
from dsRestApi import DsRestApi

class ExperimentDsApi(DsRestApi):
    '''
    Data Management API for accessing experiment interface provided by the
    DS service.
    '''
    
    def __init__(self, username=None, password=None, host=None, port=None, protocol=None):
        '''
        Constructor.

        :param username: DM username
        :type username: str

        :param password: DM password
        :type password: str

        :param host: DM service host
        :type host: str

        :param port: DM service port
        :type port: int

        :param protocol: DM service protocol
        :type protocol: str

        >>> api = ExperimentDsApi(username='dm', password='XYZ', host='bluegill1', port=22236, protocol='https')
        '''
        DsRestApi.__init__(self, username, password, host, port, protocol)

    @DsRestApi.execute2
    def getExperimentTypes(self):
        '''
        Get list of allowed experiment types.

        :returns: list of ExperimentType objects

        :raises AuthorizationError: in case user is not logged in

        :raises DmException: in case of any other errors

        >>> experimentTypeList = api.getExperimentTypes()
        >>> for experimentType in experimentTypeList:
        >>>     print experimentType['id'], experimentType['name']
        '''

        url = '%s/experimentTypes' % (self.getContextRoot())
        responseData = self.sendSessionRequest(url=url, method='GET')
        return self.toDmObjectList(responseData, ExperimentType)

    @DsRestApi.execute2
    def getExperiments(self):
        '''
        Get list of known experiments.

        :returns: list of Experiment objects

        :raises AuthorizationError: in case user does not have DM administrator role

        :raises DmException: in case of any other errors

        >>> experimentList = api.getExperiments()
        >>> for experiment in experimentList:
        >>>     print experiment['id'], experiment['name']
        '''

        url = '%s/experiments' % (self.getContextRoot())
        responseData = self.sendSessionRequest(url=url, method='GET')
        return self.toDmObjectList(responseData, Experiment)

    @DsRestApi.execute2
    def getExperimentsByStation(self, stationName):
        '''
        Get list of experiments on a given station.

        :param stationName: DM station name
        :type stationName: str

        :returns: list of Experiment objects

        :raises InvalidRequest: if station name is empty or None

        :raises AuthorizationError: in case user is not authorized to manage the given DM station

        :raises DmException: in case of any other errors

        >>> experimentList = api.getExperimentsByStation()
        >>> for experiment in experimentList:
        >>>     print experiment['id'], experiment['name']
        '''

        url = '%s/experimentsByStation/%s' % (self.getContextRoot(), stationName)
        if not stationName:
            raise InvalidRequest('Experiment station name must be provided.')
        responseData = self.sendSessionRequest(url=url, method='GET')
        return self.toDmObjectList(responseData, Experiment)

    @DsRestApi.execute2
    def getExperimentByName(self, name):
        '''
        Get experiment.

        :param name: experiment name
        :type name: str

        :returns: Experiment object

        :raises InvalidRequest: if experiment name is empty or None

        :raises AuthorizationError: in case user is not authorized to manage the DM station to which this experiment belongs

        :raises DmException: in case of any other errors

        >>> experiment = api.getExperimentByName('test01')
        >>> print experiment['id']
        '''

        url = '%s/experimentsByName/%s' % (self.getContextRoot(), name)
        if name is None or not len(name):
            raise InvalidRequest('Experiment name must be provided.')
        responseDict = self.sendSessionRequest(url=url, method='GET')
        return Experiment(responseDict)

    @DsRestApi.execute2
    def getExperimentById(self, id):
        '''
        Get experiment.

        :param id: experiment id
        :type id: int

        :returns: Experiment object

        :raises InvalidRequest: if experiment id is None

        :raises AuthorizationError: in case user is not authorized to manage the DM station to which this experiment belongs

        :raises DmException: in case of any other errors

        >>> experiment = api.getExperimentById(123)
        >>> print experiment['name']
        '''

        url = '%s/experimentsById/%s' % (self.getContextRoot(), id)
        if id is None:
            raise InvalidRequest('Experiment id must be provided.')
        responseDict = self.sendSessionRequest(url=url, method='GET')
        return Experiment(responseDict)

    @DsRestApi.execute
    def startExperiment(self, name):
        url = '%s/experiments/start' % (self.getContextRoot())
        if name is None or not len(name):
            raise InvalidRequest('Experiment name must be provided.')
        url += '?name=%s' % Encoder.encode(name)
        responseDict = self.sendSessionRequest(url=url, method='PUT')
        return Experiment(responseDict)

    @DsRestApi.execute
    def updateExperiment(self, name):
        url = '%s/experiments/update' % (self.getContextRoot())
        if name is None or not len(name):
            raise InvalidRequest('Experiment name must be provided.')
        url += '?name=%s' % Encoder.encode(name)
        responseDict = self.sendSessionRequest(url=url, method='PUT')
        return Experiment(responseDict)

    @DsRestApi.execute
    def stopExperiment(self, name):
        url = '%s/experiments/stop' % (self.getContextRoot())
        if name is None or not len(name):
            raise InvalidRequest('Experiment name must be provided.')
        url += '?name=%s' % Encoder.encode(name)
        responseDict = self.sendSessionRequest(url=url, method='PUT')
        return Experiment(responseDict)

    @DsRestApi.execute2
    def addExperiment(self, name, stationName, typeName, description, startDate, endDate):
        '''
        Add experiment.

        :param name: experiment name 
        :type name: str

        :param stationName: DM station name 
        :type stationName: str

        :param typeName: experiment type
        :type typeName: str

        :param description: experiment description
        :type description: str

        :param startDate: experiment start date
        :type startDate: str

        :param endDate: experiment end date
        :type endDate: str

        :returns: Experiment object

        :raises InvalidRequest: if one of the required arguments (experiment name, station name and experiment type) is empty or None

        :raises AuthorizationError: in case user is not authorized to manage the DM station to which this experiment belongs

        :raises ObjectAlreadyExists: if experiment with a given name already exists

        :raises DmException: in case of any other errors

        >>> experiment = api.addExperiment(name='test01', stationName='TEST', typeName='TEST')
        >>> print experiment['id']
        '''

        url = '%s/experiments' % (self.getContextRoot())
        if not name:
            raise InvalidRequest('Experiment name must be provided.')
        url += '?name=%s' % Encoder.encode(name)
        if not stationName:
            raise InvalidRequest('Experiment station name must be provided.')
        url += '&stationName=%s' % Encoder.encode(stationName)
        if not typeName:
            raise InvalidRequest('Experiment type must be provided.')
        url += '&typeName=%s' % Encoder.encode(typeName)
        if description is not None:
            url += '&description=%s' % Encoder.encode(description)
        if startDate is not None:
            url += '&startDate=%s' % Encoder.encode(startDate)
        if endDate is not None:
            url += '&endDate=%s' % Encoder.encode(endDate)
        responseDict = self.sendSessionRequest(url=url, method='POST')
        return Experiment(responseDict)

#######################################################################
# Testing.

if __name__ == '__main__':
    api = ExperimentDsApi('sveseli', 'sveseli', 'zagreb.svdev.net', 33336, 'http')
    print api.startExperiment('experiment1')