XrdCmsClient.hh

Go to the documentation of this file.

#ifndef __CMS_CLIENT__
#define __CMS_CLIENT__
/******************************************************************************/
/*                                                                            */
/*                       X r d C m s C l i e n t . h h                        */
/*                                                                            */
/* (c) 2007 by the Board of Trustees of the Leland Stanford, Jr., University  */
/*                            All Rights Reserved                             */
/*   Produced by Andrew Hanushevsky for Stanford University under contract    */
/*              DE-AC02-76-SFO0515 with the Department of Energy              */
/*                                                                            */
/* This file is part of the XRootD software suite.                            */
/*                                                                            */
/* XRootD is free software: you can redistribute it and/or modify it under    */
/* the terms of the GNU Lesser General Public License as published by the     */
/* Free Software Foundation, either version 3 of the License, or (at your     */
/* option) any later version.                                                 */
/*                                                                            */
/* XRootD is distributed in the hope that it will be useful, but WITHOUT      */
/* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or      */
/* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public       */
/* License for more details.                                                  */
/*                                                                            */
/* You should have received a copy of the GNU Lesser General Public License   */
/* along with XRootD in a file called COPYING.LESSER (LGPL license) and file  */
/* COPYING (GPL license).  If not, see <http://www.gnu.org/licenses/>.        */
/*                                                                            */
/* The copyright holder's institutional names and contributor's names may not */
/* be used to endorse or promote products derived from this software without  */
/* specific prior written permission of the institution or contributor.       */
/******************************************************************************/

class  XrdOucEnv;
class  XrdOucErrInfo;
class  XrdOucLogger;
class  XrdOucTList;
struct XrdSfsPrep;
class  XrdSysLogger;

/******************************************************************************/
/*                    R e t u r n   C o n v e n t i o n s                     */
/******************************************************************************/
  
/* The following return conventions are use by Forward(), Locate(), & Prepare()
   Return Val   Resp.errcode          Resp.errtext
   ---------    -------------------   --------
   SFS_DATA     Length of data.       Data to be returned to caller.
                Action: Caller is provided data as successful response.

   SFS_ERROR    errno                 Error message text.
                Action: Caller given error response.

   SFS_REDIRECT port (0 for default)  Host name
                Action: Caller is redirected to <host>:<port>

   SFS_STARTED  Expected seconds      n/a
                Action: Caller is told to wait for the "expected seconds" for a
                        callback with the result. A callback must follow.
                        See how to do callbacks below.

   > 0          Wait time (= retval)  Reason for wait
                Action: Caller told to wait retval seconds and retry request.

   < 0          Error number          Error message
                Action: Same as SFS_ERROR. You should *always* use SFS_ERROR.

   = 0          Not applicable        Not applicable (see below)
                Action: Forward() -> Return success; request forwarded.
                        Locate()  -> Redirection does not apply, operation
                                     should be done against local file system.
                        Prepare() -> Return success, request submitted.
*/

/******************************************************************************/
/*                  C a l l b a c k   C o n v e n t i o n s                   */
/******************************************************************************/
  
/* Most operations allow you to return SFS_STARTED to setup a callback.
   Callback information is contained in the XrdOucErrInfo object passed to
   Forward(), Locate() and Prepare(); the only methods that can apply callbacks.
   Use a callback when the operation will take at least several seconds so as
   to not occupy the calling thread for an excessive amount of time.

   The actual mechanics of a callback are rather complicated because callbacks
   are subject to non-causaility if not correctly handled. In order to avoid
   such issues, you should use the XrdOucCallBack object (see XrdOucCallBack.hh)
   to test for applicability, setup, and effect a callback.

   When calling back, you return the same information you would have returned
   had the execution path been synchronous. From that standpoint callbacks are
   relatively easy to understand. All you are doing is defering the return of
   information without occupying a thread while waiting to do so.

   A typical scenario, using Resp and the original ErrInfo object, would be....

   XrdOucCallBack cbObject;  // Must be persistent for the callback duration

   if (XrdOucCallBack::Allowed(Resp))
      {cbObject.Init(Resp);
       <hand off the cbObject to a thread that will perform the work>
       Resp.setErrCode(<seconds end-point should wait>);
       return SFS_STARTED; // Effect callback response!
      }

   Once the thread doing the work has a result, send it via a callback as if
   the work was done in a synchronous fashion.

   cbObject->Reply(retValue, ErrCodeValue, ErrTextValue);
*/

/******************************************************************************/
/*                    C l a s s   X r d C m s C l i e n t                     */
/******************************************************************************/
  
class XrdCmsClient
{
public:

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual void   Added(const char *path, int Pend=0) { (void)path; (void)Pend; }

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Configure(const char *cfn, char *Parms, XrdOucEnv *EnvInfo) = 0;

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Forward(XrdOucErrInfo &Resp,   const char *cmd,
                       const char    *arg1=0, const char *arg2=0,
                       XrdOucEnv     *Env1=0, XrdOucEnv  *Env2=0)
{
  (void)Resp; (void)cmd; (void)arg1; (void)arg2; (void)Env1; (void)Env2;
  return 0;
}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    isRemote() {return myPersona == XrdCmsClient::amRemote;}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Locate(XrdOucErrInfo &Resp, const char *path, int flags,
                      XrdOucEnv  *Info=0) = 0;

//------------------------------------------------------------------------------
// Return:    A list of managers or null if none exist.
//------------------------------------------------------------------------------

virtual
XrdOucTList   *Managers() {return 0;}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs,
                       XrdOucEnv  *Info=0)
{
  (void)Resp; (void)pargs; (void)Info;
  return 0;
}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual void   Removed(const char *path) { (void)path; }

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual void   Resume (int Perm=1) { (void)Perm; }

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual void   Suspend(int Perm=1) { (void)Perm; }

// The following set of functions can be used to control whether or not clients
// are dispatched to this data server based on a virtual resource. The default
// implementations do nothing.
//
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Resource(int n)   { (void)n; return 0;}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Reserve (int n=1) { (void)n; return 0;}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Release (int n=1) { (void)n; return 0;}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual int    Space(XrdOucErrInfo &Resp, const char *path,
                     XrdOucEnv  *Info=0) = 0;

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

        enum   Persona {amLocal,  
                        amRemote, 
                        amTarget  
                       };

               XrdCmsClient(Persona acting) : myPersona(acting) {}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

virtual       ~XrdCmsClient() {}

protected:

Persona        myPersona;
};

/******************************************************************************/
/*              I n s t a n t i a t i o n   M o d e   F l a g s               */
/******************************************************************************/
  
namespace XrdCms
{
enum  {IsProxy  = 1, 
       IsRedir  = 2, 
       IsTarget = 4, 
       IsMeta   = 8  
      };
}

/******************************************************************************/
/*               C M S   C l i e n t   I n s t a n t i a t o r                */
/******************************************************************************/

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

class XrdOss;

typedef XrdCmsClient *(*XrdCmsClient_t)(XrdSysLogger *, int, int, XrdOss *);

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

namespace XrdCms
{
          XrdCmsClient *GetDefaultClient(XrdSysLogger *Logger,
                                         int           opMode,
                                         int           myPort
                                        );
}

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#endif