00001 // -*- C++ -*- 00002 /*************************************************************************** 00003 * 00004 * The IPPL Framework 00005 * 00006 * 00007 * Visit http://people.web.psi.ch/adelmann/ for more details 00008 * 00009 ***************************************************************************/ 00010 00011 #ifndef DATA_SOURCE_H 00012 #define DATA_SOURCE_H 00013 00014 /*********************************************************************** 00015 * 00016 * DataSource is the base class for all objects which desire to have their 00017 * contents available for another program or data processing API (e.g., 00018 * visualization). It provides an interface to do the following actions: 00019 * 1. CONNECT the object with the external program or API, by providing 00020 * a name to use. 00021 * Method: DataConnect *connect(char *name, DataConnect * = 0) 00022 * 2. UPDATE the receiver end with the latest version of the data. 00023 * Method: bool update() 00024 * 3. INTERACT with the receiver, by handing off control to them until 00025 * they are finished (for some receivers, this may be a no-op). 00026 * Method: bool interact() 00027 * 4. DISCONNECT from the receiver. If not done explicitely, this will 00028 * be done when the DataSource is deleted. 00029 * Method: bool disconnect() 00030 * 00031 * To construct a DataSource, a specific subclass of DataSourceObject 00032 * must be created, which provides the particular implementation of 00033 * these interface functions based on the type of data (ParticleAttrib 00034 * or Field) and the destination of the data (e.g., PAWS, ACL viz, etc.) 00035 * 00036 * Objects in Ippl which want to be a source for data to some other 00037 * agency should then do the following: 00038 * 1. Make your new class be derived from DataSource; 00039 * 2. Define a version of the protected virtual function 00040 * 'makeDataSourceObject'. This function should create the proper 00041 * subclass of DataSourceObject based on the new class' type and the 00042 * method for connection. 00043 * 00044 ***********************************************************************/ 00045 00046 // include files 00047 #ifdef IPPL_STDSTL 00048 #include <vector> 00049 using std::vector; 00050 #else 00051 #include <vector.h> 00052 #endif // IPPL_STDSTL 00053 00054 00055 // forward declarations 00056 class DataSourceObject; 00057 class DataConnect; 00058 00059 00060 // A base class for all objects in IPPL which we want to make accessible 00061 // to external agencies (basically, ParticleAttrib's and Field's) 00062 class DataSource { 00063 00064 public: 00065 // enumeration of data transfer directions: 00066 // input = obtain data from external agency 00067 // output = send data to external agency 00068 // both = can send and receive (meaning depends on context) 00069 // default = get transfer direction from default setting in connect obj 00070 enum DsMode { INPUT, OUTPUT, BOTH, DEFAULT }; 00071 00072 // container type for connections 00073 typedef vector<DataSourceObject *> container_t; 00074 00075 public: 00076 // constructor 00077 DataSource(); 00078 00079 // destructor 00080 virtual ~DataSource(); 00081 00082 // 00083 // informative methods 00084 // 00085 00086 // are we currently connected to a DataConnect object? If an argument is 00087 // given, just check if we're connected to the specified DataConnect (else, 00088 // just report if we're connected to anyone). 00089 bool connected(DataConnect * = 0) const; 00090 00091 // find the first DataSourceObject which is connected to the given 00092 // DataConnect, and return it; otherwise, return 0 00093 DataSourceObject *findDataSourceObject(DataConnect *) const; 00094 00095 // 00096 // DataSource interface ... these mainly call the virtual functions in 00097 // the provided object 00098 // 00099 00100 // Register an object as something that can be a source of data. 00101 // Arguments = name of item, connection to use, and type of 00102 // connection (INPUT, OUTPUT, BOTH, or DEFAULT). If the connection 00103 // has not been created yet (e.g., it is NULL), create a new default 00104 // connection (or use the existing default one). Return the connection. 00105 DataConnect *connect(const char *, DataConnect * = 0, 00106 int = DataSource::DEFAULT); 00107 00108 // Register the given DataSourceObject directly. This is simpler than 00109 // the above version of connect, since the DataSourceObject has already 00110 // been created. It can be used to register most any type of connection, 00111 // even one using DataConnect objects that are not part of IPPL itself. 00112 // Return success. 00113 bool connect(DataSourceObject *); 00114 00115 // Disconnect an object from the DataConnect object. Return success. 00116 // If no DataConnect is specified, disconnect from ALL connections. 00117 bool disconnect(DataConnect * = 0); 00118 00119 // Update the object, that is, make sure the receiver of the data has a 00120 // current and consistent snapshot of the current state. Return success. 00121 bool updateConnection(DataConnect * = 0); 00122 00123 // Indicate to the receiver that we're allowing them time to manipulate the 00124 // data (e.g., for a viz program, to rotate it, change rep, etc.) 00125 // This should only return when the manipulation is done. For some cases, 00126 // this will be a no-op. 00127 void interact(DataConnect * = 0); 00128 00129 // Pass on a string to the connection, most likely to give it a 00130 // command to do some action. Similar to the above interact, except 00131 // the request for interaction involves the given string 00132 void interact(const char *, DataConnect * = 0); 00133 00134 protected: 00135 // a virtual function which is called by this base class to get a 00136 // specific instance of DataSourceObject based on the type of data 00137 // and the connection method (the argument to the call). 00138 virtual DataSourceObject *createDataSourceObject(const char *, 00139 DataConnect *, 00140 int) = 0; 00141 00142 private: 00143 // the list of connected DataSourceObject's 00144 container_t ConnectionList; 00145 }; 00146 00147 #endif // DATA_SOURCE_H 00148 00149 /*************************************************************************** 00150 * $RCSfile: DataSource.h,v $ $Author: adelmann $ 00151 * $Revision: 1.1.1.1 $ $Date: 2003/01/23 07:40:25 $ 00152 * IPPL_VERSION_ID: $Id: DataSource.h,v 1.1.1.1 2003/01/23 07:40:25 adelmann Exp $ 00153 ***************************************************************************/