XrdCmsClient.hh

Go to the documentation of this file.
00001 #ifndef __CMS_CLIENT__
00002 #define __CMS_CLIENT__
00003 /******************************************************************************/
00004 /*                                                                            */
00005 /*                       X r d C m s C l i e n t . h h                        */
00006 /*                                                                            */
00007 /* (c) 2007 by the Board of Trustees of the Leland Stanford, Jr., University  */
00008 /*                            All Rights Reserved                             */
00009 /*   Produced by Andrew Hanushevsky for Stanford University under contract    */
00010 /*              DE-AC02-76-SFO0515 with the Department of Energy              */
00011 /*                                                                            */
00012 /* This file is part of the XRootD software suite.                            */
00013 /*                                                                            */
00014 /* XRootD is free software: you can redistribute it and/or modify it under    */
00015 /* the terms of the GNU Lesser General Public License as published by the     */
00016 /* Free Software Foundation, either version 3 of the License, or (at your     */
00017 /* option) any later version.                                                 */
00018 /*                                                                            */
00019 /* XRootD is distributed in the hope that it will be useful, but WITHOUT      */
00020 /* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or      */
00021 /* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public       */
00022 /* License for more details.                                                  */
00023 /*                                                                            */
00024 /* You should have received a copy of the GNU Lesser General Public License   */
00025 /* along with XRootD in a file called COPYING.LESSER (LGPL license) and file  */
00026 /* COPYING (GPL license).  If not, see <http://www.gnu.org/licenses/>.        */
00027 /*                                                                            */
00028 /* The copyright holder's institutional names and contributor's names may not */
00029 /* be used to endorse or promote products derived from this software without  */
00030 /* specific prior written permission of the institution or contributor.       */
00031 /******************************************************************************/
00032 
00033 class  XrdOucEnv;
00034 class  XrdOucErrInfo;
00035 class  XrdOucLogger;
00036 class  XrdOucTList;
00037 struct XrdSfsPrep;
00038 class  XrdSysLogger;
00039 
00040 /******************************************************************************/
00041 /*                    R e t u r n   C o n v e n t i o n s                     */
00042 /******************************************************************************/
00043   
00044 /* The following return conventions are use by Forward(), Locate(), & Prepare()
00045    Return Val   Resp.errcode          Resp.errtext
00046    ---------    -------------------   --------
00047    SFS_DATA     Length of data.       Data to be returned to caller.
00048                 Action: Caller is provided data as successful response.
00049 
00050    SFS_ERROR    errno                 Error message text.
00051                 Action: Caller given error response.
00052 
00053    SFS_REDIRECT port (0 for default)  Host name
00054                 Action: Caller is redirected to <host>:<port>
00055 
00056    SFS_STARTED  Expected seconds      n/a
00057                 Action: Caller is told to wait for the "expected seconds" for a
00058                         callback with the result. A callback must follow.
00059                         See how to do callbacks below.
00060 
00061    > 0          Wait time (= retval)  Reason for wait
00062                 Action: Caller told to wait retval seconds and retry request.
00063 
00064    < 0          Error number          Error message
00065                 Action: Same as SFS_ERROR. You should *always* use SFS_ERROR.
00066 
00067    = 0          Not applicable        Not applicable (see below)
00068                 Action: Forward() -> Return success; request forwarded.
00069                         Locate()  -> Redirection does not apply, operation
00070                                      should be done against local file system.
00071                         Prepare() -> Return success, request submitted.
00072 */
00073 
00074 /******************************************************************************/
00075 /*                  C a l l b a c k   C o n v e n t i o n s                   */
00076 /******************************************************************************/
00077   
00078 /* Most operations allow you to return SFS_STARTED to setup a callback.
00079    Callback information is contained in the XrdOucErrInfo object passed to
00080    Forward(), Locate() and Prepare(); the only methods that can apply callbacks.
00081    Use a callback when the operation will take at least several seconds so as
00082    to not occupy the calling thread for an excessive amount of time.
00083 
00084    The actual mechanics of a callback are rather complicated because callbacks
00085    are subject to non-causaility if not correctly handled. In order to avoid
00086    such issues, you should use the XrdOucCallBack object (see XrdOucCallBack.hh)
00087    to test for applicability, setup, and effect a callback.
00088 
00089    When calling back, you return the same information you would have returned
00090    had the execution path been synchronous. From that standpoint callbacks are
00091    relatively easy to understand. All you are doing is defering the return of
00092    information without occupying a thread while waiting to do so.
00093 
00094    A typical scenario, using Resp and the original ErrInfo object, would be....
00095 
00096    XrdOucCallBack cbObject;  // Must be persistent for the callback duration
00097 
00098    if (XrdOucCallBack::Allowed(Resp))
00099       {cbObject.Init(Resp);
00100        <hand off the cbObject to a thread that will perform the work>
00101        Resp.setErrCode(<seconds end-point should wait>);
00102        return SFS_STARTED; // Effect callback response!
00103       }
00104 
00105    Once the thread doing the work has a result, send it via a callback as if
00106    the work was done in a synchronous fashion.
00107 
00108    cbObject->Reply(retValue, ErrCodeValue, ErrTextValue);
00109 */
00110 
00111 /******************************************************************************/
00112 /*                    C l a s s   X r d C m s C l i e n t                     */
00113 /******************************************************************************/
00114   
00115 class XrdCmsClient
00116 {
00117 public:
00118 
00119 //------------------------------------------------------------------------------
00126 //------------------------------------------------------------------------------
00127 
00128 virtual void   Added(const char *path, int Pend=0) {}
00129 
00130 //------------------------------------------------------------------------------
00140 //------------------------------------------------------------------------------
00141 
00142 virtual int    Configure(const char *cfn, char *Parms, XrdOucEnv *EnvInfo) = 0;
00143 
00144 //------------------------------------------------------------------------------
00170 //------------------------------------------------------------------------------
00171 
00172 virtual int    Forward(XrdOucErrInfo &Resp,   const char *cmd,
00173                        const char    *arg1=0, const char *arg2=0,
00174                        XrdOucEnv     *Env1=0, XrdOucEnv  *Env2=0) {return 0;}
00175 
00176 //------------------------------------------------------------------------------
00181 //------------------------------------------------------------------------------
00182 
00183 virtual int    isRemote() {return myPersona == XrdCmsClient::amRemote;}
00184 
00185 //------------------------------------------------------------------------------
00212 //------------------------------------------------------------------------------
00213 
00214 virtual int    Locate(XrdOucErrInfo &Resp, const char *path, int flags,
00215                       XrdOucEnv  *Info=0) = 0;
00216 
00217 //------------------------------------------------------------------------------
00223 // Return:    A list of managers or null if none exist.
00224 //------------------------------------------------------------------------------
00225 
00226 virtual
00227 XrdOucTList   *Managers() {return 0;}
00228 
00229 //------------------------------------------------------------------------------
00237 //------------------------------------------------------------------------------
00238 
00239 virtual int    Prepare(XrdOucErrInfo &Resp, XrdSfsPrep &pargs,
00240                        XrdOucEnv  *Info=0) {return 0;}
00241 
00242 //------------------------------------------------------------------------------
00247 //------------------------------------------------------------------------------
00248 
00249 virtual void   Removed(const char *path) {}
00250 
00251 //------------------------------------------------------------------------------
00256 //------------------------------------------------------------------------------
00257 
00258 virtual void   Resume (int Perm=1) {}
00259 
00260 //------------------------------------------------------------------------------
00265 //------------------------------------------------------------------------------
00266 
00267 virtual void   Suspend(int Perm=1) {}
00268 
00269 // The following set of functions can be used to control whether or not clients
00270 // are dispatched to this data server based on a virtual resource. The default
00271 // implementations do nothing.
00272 //
00273 //------------------------------------------------------------------------------
00280 //------------------------------------------------------------------------------
00281 
00282 virtual int    Resource(int n)   {return 0;}
00283 
00284 //------------------------------------------------------------------------------
00292 //------------------------------------------------------------------------------
00293 
00294 virtual int    Reserve (int n=1) {return 0;}
00295 
00296 //------------------------------------------------------------------------------
00305 //------------------------------------------------------------------------------
00306 
00307 virtual int    Release (int n=1) {return 0;}
00308 
00309 //------------------------------------------------------------------------------
00318 //------------------------------------------------------------------------------
00319 
00320 virtual int    Space(XrdOucErrInfo &Resp, const char *path,
00321                      XrdOucEnv  *Info=0) = 0;
00322 
00323 //------------------------------------------------------------------------------
00327 //------------------------------------------------------------------------------
00328 
00329         enum   Persona {amLocal,  
00330                         amRemote, 
00331                         amTarget  
00332                        };
00333 
00334                XrdCmsClient(Persona acting) : myPersona(acting) {}
00335 
00336 //------------------------------------------------------------------------------
00338 //------------------------------------------------------------------------------
00339 
00340 virtual       ~XrdCmsClient() {}
00341 
00342 protected:
00343 
00344 Persona        myPersona;
00345 };
00346 
00347 /******************************************************************************/
00348 /*              I n s t a n t i a t i o n   M o d e   F l a g s               */
00349 /******************************************************************************/
00350   
00355 namespace XrdCms
00356 {
00357 enum  {IsProxy  = 1, 
00358        IsRedir  = 2, 
00359        IsTarget = 4, 
00360        IsMeta   = 8  
00361       };
00362 }
00363 
00364 /******************************************************************************/
00365 /*               C M S   C l i e n t   I n s t a n t i a t o r                */
00366 /******************************************************************************/
00367 
00368 //------------------------------------------------------------------------------
00400 //------------------------------------------------------------------------------
00401 
00408 //------------------------------------------------------------------------------
00421 //------------------------------------------------------------------------------
00422 
00423 namespace XrdCms
00424 {
00425           XrdCmsClient *GetDefaultClient(XrdSysLogger *Logger,
00426                                          int           opMode,
00427                                          int           myPort
00428                                         );
00429 }
00430 
00431 //------------------------------------------------------------------------------
00437 //------------------------------------------------------------------------------
00438 
00443 #endif

Generated on 16 Jan 2014 for xrootd by  doxygen 1.4.7