diff options
Diffstat (limited to 'TAO/orbsvcs/PSS/README')
| -rw-r--r-- | TAO/orbsvcs/PSS/README | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/TAO/orbsvcs/PSS/README b/TAO/orbsvcs/PSS/README new file mode 100644 index 00000000000..106a07c5dd5 --- /dev/null +++ b/TAO/orbsvcs/PSS/README @@ -0,0 +1,261 @@ + + Persistence State Service + ------------------------- + + The Persistent State Service (PSS) provides a standard way to +persistently save the state of objects in a datastore. A datastore is +an entity that manages data like a database or a set of files. For +TAO's implementation of PSS, the datastore is a normal file, for now. + + The PSS defines two ways to define the datastore schema and +the interfaces to the storage object instances in the datastore. One +way is to use the Persistent State Definition Language (PSDL). PSDL +language is a superset to the IDL language and introduces four new +constructs: storagehome, storagetype, abstract storagehome and +abstract storagetype. A PSDL file (which is similar to an IDL file) +contain the definitions which describe the interface to the +datastore. This psdl interface and the datastore is visible only to +the server which saves the state of objects. The clients to this +server do not idea about how the server saves the state of the +objects and hence have no idea about the psdl interface or the +datastore. + + The PSS implementation provides a compiler tool to process +the psdl file and generates stubs (I will use the name 'stub' just for +the lack of any other name.. though this stub is not the same as the +normal stub that is generated by the IDL compiler). + + PSDL Compiler + ============= + + TAO's implementation of the PSS provides psdl_tao as the +compiler to + +Design +====== + + The Input file (of format pidl) is first parsed with the +yacc-lex parser. The TAO_PSDL_Interpreter has a method (build_tree) +which helps construct an expression tree representing nodes from the +tokens returned by the Yacc generated parser. In addition, based on +the grammar set in PSDL.yy, any syntax errors are checked by the yacc +parser. Using the '-b' (build-tree) option, you can print out the +generated parse-tree for debugging purposes. All the classes in +PSDL_Node help build the parse tree. +(@@ To-do: I should be adding an option to the executable so that the +parse tree can be printed out when the option is set.) + + Along with the basic parsing, we build the symbol +table. The TAO_PSDL_Scope class is the base class which helps add each +type (like interface, exceptions etc) to the symbol table. + + The symbol table is constructed using the ACE hash maps. +We use two kinds of hash-maps...one maps the identifier to a +structure (Node_Info) which has information about the identifier +(identifier_type, module_name & interface_name (module and interfaces +to which this identifier belongs). This is used in cases where in the +identifier doesnt have some members in itself.. constant declarations, +typedefs, exceptions with no members etc. + + Unlike a simple declaration or a typedef, types like +interfaces have member declarations which come with their scope. For +example, an interface has its own set of declarations, methods, +interfaces etc. For such types, we will have a class derived from +base TAO_PDSL_Scope. [In the case of interfaces, it is +TAO_PSDL_Interface_Scope.] The second hash map is to +map the identifier and the instance of the identifier's +type... i.e. say the identifier is of type interface, this hash-map +has a mapping between the identifier and the pointer to the instance +of TAO_PSDL_Interface_Scope. [All the TAO_PSDL_*_Scope classes fall in +this category.] + + In this phase, along with building the symbol table, we also +do the semantic checking. Semantic checking includes checking if an +identifier that is declared before is now being redeclared. +Identifiers are case-sensitive and case-insensitive too... +ie. for ex: You cannot have CosNaming and cosnaming. + + After the symbol tables are built, the next step is to +generate code in to the stubs. The classes TAO_PSDL_*_Visitor generates +this code. TAO_PSDL_Node_Visitor is the base class and the derived +classes override the necessary methods. So, if you want to generate +for some other type in future, we need to have another of +TAO_PSDL_*_Visitor class and override the necessary virtual method. + + +Implementation files of the stubs (idlC.cpp) +================================= + + The generation of the header and implementation files +for the stubs can be done in a single pass. The implementation files +mainly involves the '<<' and '>>' operator support. These operators +support will be mainly useful while marshalling and demarshalling the +data types. + + + + +Status in a summary. +======= + +1. Can parse any psdl file. +2. Does syntax checking. +3. Can build parse tree for most but not all of the types. +4. Builds ASTs for the basic types which includes typedefs, + interfaces, structs, modules, exceptions, constant declarations. +5. Generate the code that goes into the header file for the same types + listed above. + + +Files and Description +===================== + +PSDL.yy Yacc file which has the PSDL grammar. + +PSDL_y.cpp +PSDL_y.h Yacc generated files. + +PSDL_l.cpp Lex generated file. + +PSDL_Node.h +PSDL_Node.cpp Each node in the parse tree is derived from + the base type TAO_PSDL_Node. The classes in + this file provide the interface for the + different types. Each class will have accessor + methods to access the private members and an + accept method to invoke the corresponding + visitor method. (We are applying the visitor + pattern here.) + + +PSDL_Scope.h +PSDL_Scope.cpp +PSDL_*_Scope.* The classes in these files are useful for + building the AST. TAO_PSDL_Scope is the base + class and there are classes for each type + (which has members in it, ex: interface) + which needs to be added to the AST which + derive from TAO_PSDL_Scope. + +PSDL_Node_Visitor.h +PSDL_Node_Visitor.cpp +PSDL_*_Visitor.* TAO_PSDL_Node_Visitor acts as a base class + useful for generating code into + stubs. TAO_PDSL_Node_Visitor derives from + TAO_PSDL_Scope_Visitor. The sub-classes (for + the different types) which + need to override the basic functionality of + the visitor methods in TAO_PSDL_Node_Visitor + derive from it and override accordingly. The +derived classes methods are invoked from the base class as needed +making use of the factory pattern (TAO_PSDL_Visitor_Factory). + + +To-Do +==== + +1. The visitor classes should generate the code into a file and not to + stdout as I am doing now. + +2. Support for comments , pragmas etc. Right now, if you have + comments or pragmas, its going to fail. + +Test +==== + +% ./psdl_tao < trial_idl.idl + + +Things to do +============ + + +1. Have a test to include all the existing types. Should check the + generated code and check if it is the right thing. - 2 days + +2. Work on the stubs. + . Redirect the output to a file rather than to stdout. + . Work on the implementation files (*C.cpp). This will be based on + ACE Reliable Multicast framework. + ps: Bala told last friday that ACE Reliable Multicast Framework + has several bugs. So, this might end up taking longer. FYI, + + - 2 weeks. + +3. Have a test/example for the total framework. 1 week- 10 days + + - Have an application which is going to use the PSS framework.. have a server etc. + +4. Additional Documentation as needed including + . Steps for modifying the existing services to use PSS. 1 week. + + +5. Include support for all the types in PSDL language in all the + stages which includes mainly + . Building the parse tree + . While building ASTs + . Generating the stubs. + +6. Extend the tests to include all the new types. + + + +IMR +=== + +1. Test + +2. Documentation abt the differences between old and new IMR. +3. How to update/migrate to the new IMR. + +4. Code review. 2 days +5. modift 2 days. + + +MInor things +============ + +1. Print out the Caps of the names + +#if !defined (_TRIAL_INTERFACE___PTR_CH_) + +instead of + +#if !defined (__trial_interface___PTR_CH_) + + +2. Check out TAO_NAMESPACE_STORAGE_CLASS and static nad extern storage classes before _tc_* + + +Notes on how to proceed +======================= + +1. Serialize the data using TAO_OutputCDR. + +The implementation files should have the '<<' and '>>' methods. + +2. There needs to be another executable or library which would be +actually saving the state of objects to the database. Since RMCast is +not working right now, we can save the data to a file and retrieve +from it. + + +Example +======= + +1. Have a mini naming idl which just has the bind and find functions + support. + + There can be just a server.cpp which will bind information. + +2. Have a psdl interface which has a + + sequence of struct (name, + stringified_ior). + + When a bind is done, it has to be going through the helper +classes and inserted into a hash_map and saved to the file. And when +find is invoked, it has to be read from the file and demarshalled. + + + |