// !!!!!!!!!!!!!!!!!!!!!!!!!!!    NOTICE   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
//  
// THIS IDL FILE SHOULD NOT BE RELIED UPON IN BUILDING SAM CLIENTS.
//
// This IDL file is included here in the sam_doc/doc/design folder for purposes
// of communication of the design of a future IDL.  Once the design is stabilized
// the eventual IDL will be part of the sam_db_server_idl product with all future
// enhancements made there.  This file will get stale with age!  Matt Vranicar
//
// !!!!!!!!!!!!!!!!!!!!!!!!!!!    NOTICE   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

//##############################################################################
// Project   : SAM
// Package   : sam_dbserver
//
// This work is part of a development project, called SAM, which consists of a
// number of coordinated packages each named sam_xxxx .
//
// Notice of authorship, copyright status,  and terms and conditions, should
// the software eventually become available for use outside Fermilab, can be
// found in the README and LICENCE files in the top level directory of the main
// sam package.
//#############################################################################

//---------------------------------------------------------------------------
// Copyright (C) Fermi National Accelerator Laboratory 1998
// All Rights Reserved.
//
// Project:      SAM
// File:         $Source: /cvs/cd/sam_doc/doc/design/Station.idl,v $
// Version:      $RCSfile: Station.idl,v $
// Modified:     $Date: 1999/11/19 23:58:12 $ : $Author: vranicar $
//
//---------------------------------------------------------------------------

#ifndef Station_idl
#define Station_idl

#include "SAMDbException.idl"
#include <SAMTypedef.idl>

module SAMDbServer {

  //
  //-----------------------------------------------------------------
  //-----------------------------------------------------------------
  //
  // Station Interface.
  //
  interface Station {

	struct  Project   {
		long projectId;
		string projectName;
	};

	typedef sequence<Project> Projects;

	struct ProjectInfo { 
	    long   projectId;
	    string projectName;
	    string projectStatus;
	};

        struct StationInfo {
		long   stationId;
		string stationName;
	};

	typedef sequence<ProjectInfo> ProjectInfoSet;

	typedef sequence<StationInfo> Stations;

        // Can you talk to the Station Servant?
        string hello()
            raises(InternalException);


	ProjectInfoSet getRunningProjects(in string stationName)
		raises (StationNotFound, DBError,InternalException);

	Stations getStations()
		raises (DBError,InternalException);

	long getStationId(in string stationName)
        	raises (StationNotFound, DBError,InternalException);

	//
	// Create a new project, recording the station on which it will be started,
	// and return the project id.
	//
	long createProject (
		in string projectName,
		in string stationName,
		in ProjDefKey projDef,
                in long   snapshotVersion,
		in UserInfo userInfo)
            raises(StationNotFound,
                   ProjectDefinitionNotFound,
		   ProjectSnapshotNotFound,
		   UserNotFound,
		   WorkGroupNotFound,
		   PersonWorkGroupNotFound,
                   ProjectDuplicate,
                   NoProjectFiles,
		   DBError,InternalException);


	//
	// Find all the projects running on a station, given the station name.
	// NO IMPLEMENATION BEHIND IT YET!
	//
	Projects getProjectsByStation(in string stationName)
            raises(ProjectNotFound,
                   StationNotFound,
                   DBError,InternalException);

	//
	// Find all the projects running on a station, given a station id.
	// NO IMPLEMENATION BEHIND IT YET!
	//
	Projects getProjectsByStationId(in long stationId)
            raises(ProjectNotFound,
                   StationNotFound,
                   DBError,InternalException);

	//
	////////////////////////////////////////////////////
	// NEW STATION DESIGN
	//

	// Structs and sequences used below.

	enum DiskStatus { ---what values do we want here?--- };

	struct CachedFileProjectUsage {
	  long   fileId;     // I can drop this, but that limits the use of this struct
	  long   projectId;
	  string startTime;  // date and time the file was given to a project
	  string endTime;    // date and time the project was done with it
	};

	typedef sequence<CachedFileProjectUsage> CachedFileProjects;

	struct CachedFile {
	  long   diskId;     // I can drop this, but that limits the use of this struct
	  long   fileId;
	  string directory;
	  string startTime;  // date and time the file was cached
	  string endTime;    // date and time removed from cache
	  CachedFileProjects projects;
	};

	typedef sequence<CachedFile> StationDiskFileCache;

	struct StationDiskInfo {
	  long   diskId;
	  string machine;
	  string mountPoint;
	  long   size;
	  string status;
	  string description;
	  StationDiskFileCache fileCache;
	};

	typedef sequence<StationDiskInfo> StationDisks;

	//
	// Get Station initialization contents.
	// 
	StationDisks getStationDetails ( in string stationName )
	  raises ( Well, maybe a lot,
		   we will see all that is raises as I put together the dbServer logic,
		   DBError, InternalException );

	//
	// Record that a file has been cached on a station, 
	// including the full directory location of the file.
	// This enforces that the file is cached only once
	// on the disk indicated.  (Or only once per station?)
	//
	fileCached ( in string 	fileName,
		     in long 	diskId,
		     in string	directory )
	  raises ( FileNotFound,
		   DiskNotFound,
		   FileLocationNotFound,
		   DuplicateFileCache,
		   DBError, InternalException );
		   
	//
	// Record that a file has been removed from cache.
	//
	fileUncached ( in string fileName,
		       in long   diskId,
		       in string directory)
	  raises ( FileNotFound,
		   DiskNotFound,
		   FileLocationNotFound,
		   FileCacheNotFound,
		   DBError, InternalException );

	//
	// Record that a file was presented to an
	// analysis project for consumption.
	//
	fileGiven2Project ( in string fileName,
			    in long   projectId,
			    in long   diskId )
	  raises ( FileNotFound,
		   ProjectNotFound,
		   DiskNotFound,
		   FileCacheNotFound,
		   FileAlreadyGiven2Project,
		   DBError, InternalException );

	//
	// Record that a project is done with a cached file.
	//
	projectDoneWithFile ( in string fileName,
			      in long   projectId,
			      in long   diskId )
	  raises ( FileNotFound,
		   ProjectNotFound,
		   DiskNotFound,
		   FileCacheNotFound,
		   FileNotGiven2Project,
		   DBError, InternalException );

	//////////////////////////////////////////////////
	// STATION MAINTENANCE
	//

	//
	// Add a disk to a station, return the disk id.
	//
	long addDisk ( in string stationName,
		       in string machine,      // or nodeId?
		       in string mountPoint,
		       in long   size,
		       in string description,
		       in DiskStatus status )
	  raises ( StationNotFound,
		   NodeNotFound,               // I guess?
		   DBError, InternalException );

	//
	// Delete a disk from a station, but not if
	// any files are cached on this disk.
	// If you know the disk id, the second method is fastest.
	// 
	deleteDisk ( in string stationName,
		     in string machine,
		     in string mountPoint )
	  raises ( StationNotFound,
		   NodeNotFound,               // I guess?
		   DiskNotFound,
		   FilesCachedOnDisk,
		   DBError, InternalException );

	deleteDiskById ( in long diskId )
	  raises ( DiskNotFound,
		   FilesCachedOnDisk,
		   DBError, InternalException );
	
	// 
	// Find a disk, returning all you know about the disk..
	//
	StationDiskInfo getDisk ( in string stationName,
				  in string machine,
				  in string mountPoint )
	  raises ( StationNotFound,
		   NodeNotFound,
		   DiskNotFound,
		   DBError, InternalException );

	//
	// Add to the list of valid disk locations.
	//
	addDiskLocation ( in string fullPath )
	  raises (DuplicateDiskLocation,
		  DBError, InternalException);

	//
	// Remove a file from cache - the hard way.
	// IS THIS REALLY NEEDED HERE?  IT IS ALREADY PART OF File.idl.
	//
	void eraseFileLocation ( in string	 fileName,
				 in LocationInfo fileLocation)
	  raises(DBError, DataFileNotFound, InternalException);

  };
};

#endif