doc/salome/salome_file.dox

   1 /*!
   2
   3 \page salome_file_page Salome_file
   4
   5 This page introduces the Salome_file feature. Salome_file is based on the
   6 SALOME_FileTransfer. It extends it to enable a higher model for managing files into
   7 %SALOME applications.
   8
   9 \section S1_Salome_file Principles
  10
  11 Salome_file is a CORBA %object. It's role is to managed many system files. When a Salome_file
  12 is created, no files are managed. Then, files are added using Salome_file_i interface. %A file is represented
  13 by a <b>name</b> and a <b>path</b>.
  14
  15 There is two different cases when a file is added :
  16
  17 - <b>Local file</b> : the file added exists or it will be created by the user with the path and the name used in
  18 its registration.
  19 - <b>Distributed file</b> : the file added exists into a distributed localization.
  20
  21 To be able to get a distributed file, the Salome_file has to be connected with an another Salome_file that
  22 managed this file. This distributed Salome_file could be located into a distributed resource.
  23
  24 \section S2_Salome_file Simple example
  25
  26 This section shows a simple example of the use of Salome_file. The objective is to create
  27 two Salome_file; one is managing a local file, the other is managing a distributed file.
  28 Then, these Salome_files are connected to enable the copy of the real file gbetween the two Salome_files.
  29
  30 Firstly, two Salome_files are created :
  31
  32 \code
  33 #include "Salome_file_i.hxx"
  34
  35 int main (int argc, char * argv[])
  36 {
  37   Salome_file_i file_source;
  38   Salome_file_i file_dest;
  39
  40 \endcode
  41
  42 Secondly, the real files are registered into the Salome_files.
  43
  44 \code
  45  file_source.setLocalFile("/bin/cat");
  46  file_dest.setDistributedFile("/tmp/cat_copy");
  47 \endcode
  48
  49 Thirdly, we connect the destination file with the source file :
  50
  51 \code
  52   file_dest.connect(file_source);
  53 \endcode
  54
  55 Finally, the file is sended using Salome_file interface.
  56
  57 \code
  58   file_dest.recvFiles();
  59   // Status check
  60   state = file_dest.getSalome_fileState();
  61   print_state(state); // You have to implement this function.
  62 };
  63 \endcode
  64
  65 \section S3_Salome_file Advanced example
  66
  67 This advanced example illustrates a part of the Salome_file API dedicated
  68 for situations where multiple files are managed.
  69
  70 This is the situation :
  71
  72 \code
  73
  74 #include "Salome_file_i.hxx"
  75
  76 int main (int argc, char * argv[])
  77 {
  78   Salome_file_i file_source_a;
  79   Salome_file_i file_source_b;
  80   Salome_file_i file_dest;
  81
  82   file_source_a.setLocalFile("/bin/cat");
  83   file_source_a.setLocalFile("/bin/ls");
  84
  85   file_source_b.setLocalFile("/bin/echo");
  86   file_source_b.setLocalFile("/bin/cp");
  87
  88   file_dest.setDistributedFile("/tmp/cat_copy");
  89   file_dest.setDistributedFile("/tmp/echo_copy");
  90 \endcode
  91
  92 There is two problems in this case.
  93
  94 The first problem is in the <b>file_dest</b> Salome_file, there is two files. If
  95 the method connect is used, the Salome_file cannot know if the reference is for <b>cat_copy</b> or
  96 <b>echo_copy</b>. Indeed <b>echo_copy</b> could be provided by another Salome_file that for <b>cat_copy</b>.
  97
  98 The second problem comes from the two files of <b>file_source_a</b> Salome_file. Indeed when connect is used,
  99 there is no information about the choice of the source file into the source Salome_file. For
 100 <b>cat_copy</b>, did the used want <b>cat</b> or <b>echo</b> ?
 101
 102 To avoid these cases, Salome_file API provides advanced methods :
 103
 104 \code
 105   file_dest.connectDistributedFile("cat_copy", file_source_a);
 106   file_dest.setDistributedSourceFile("cat_copy", "cat");
 107
 108   file_dest.connectDistributedFile("cat_echo", file_source_b);
 109   file_dest.setDistributedSourceFile("cat_echo", "echo");
 110
 111   file_dest.recvFiles();
 112   // Status check
 113   state = file_dest.getSalome_fileState();
 114   print_state(state); // You have to implement this function.
 115 };
 116 \endcode
 117
 118 */