Index: extend-user-howto.xml =================================================================== RCS file: /home/cvspublic/jakarta-turbine-2/xdocs/howto/extend-user-howto.xml,v retrieving revision 1.7 diff -u -r1.7 extend-user-howto.xml --- extend-user-howto.xml 13 May 2002 19:51:46 -0000 1.7 +++ extend-user-howto.xml 11 Dec 2002 06:35:41 -0000 @@ -3,6 +3,7 @@ Extend User Howto + Quinton McCombs Jon S. Stevens Dan A. Bachelder Scott B. Eade @@ -28,11 +29,12 @@

- The example herein uses TDK 2.1 and the TDK sample application Newapp. + The example herein uses a very simple object model with only one table. + This table would be defined in your project-schema.xml file. To illustrate solutions to both of out motivators we will:

  1. - Add a CREATE_USER_ID column to the RDF application table. + Add a REVIEWED_BY_USER_ID column to the BOOK application table.
  2. Add a TITLE column to TURBINE_USER. @@ -45,58 +47,54 @@ a transaction. See the very end of this howto for further details.

    - First we update the schema for the project (in this case - newapp-schema.xml) to include an alias definition of TurbineUser (which + Here is the sample project-schema.xml file before making modifications + to reference TURBINE_USER. + + + + + + +
    + ]]> +

    +

    + First we update the schema for the project (project-schema.xml) + to include an alias definition of TurbineUser (which will NOT create a new table) as well as the desired foreign key references. Note how the TurbineUser definition refers to a pair of adapter classes (that we will create shortly) and how it is only necessary to define the columns we are referring to as foreign keys elsewhere in the application database. Note also the addition of - CREATE_USER_ID as a foreign key in the RDF table. + REVIEWED_BY_USER_ID as a foreign key in the BOOK table.

    - - - - - - - - - - - - - - - -
    ]]> -

    - The columns we want to add to TurbineUser must be defined in - turbine-schema.xml thus: + + + +
    + + + + + + + + +
    +     ]]> +

    + Although we are adding a column to TURBINE_USER, do not modify + turbine-schema.xml. This will only make things more confusing. Insetad, + rename your turbine-schema.xml file to turbine-schema.original. This will + also prevent the org.mycompany.sampleapp.om.Turbine* and + org.mycompany.sampleapp.om.BaseTurbine* object from beging generated + during the project-om ant task. This is not a problem as these objects + are not used.

    - - - - - - - - - - - - - - - - - ]]>

    Before we create the adapter classes referred to above we will first extend TurbineMapBuilder in order to tell Turbine about the additional @@ -109,12 +107,12 @@ into the temp hashtable if you like this).

    @@ -161,18 +157,19 @@ setPerm() directly.

    -

    - We can now use "ant project-om" to generate our OM layer using - the adapter classes we defined above. Note that "ant init" - (WARNING: THE init TARGET WILL DELETE ALL DATA IN - YOUR DATABASE), or any other target that triggers a compile of - the OM layer will result in a compile error of BaseRdf due to - the fact that NewappUserPeer does not implement a retrieveByPK() - method. -

    -

    - So lets implement retrieveByPK() so that everything can compile. This - needs to be implemented in NewappUserPeer which was generated by torque - when we executed project-om above (but it won't be deleted should we need - to regenerate the OM layer at some stage in the future - like in about 2 - minutes). -

    -

    - Now we can use "ant init" to generate the rest of the things it - generates - this will include the regenreation of the OM layer, the - generation of the sql to create the database tables and the actual - execution of this sql to recreate the database tables to now include any - additional columns we have defined (AS A CONSEQUENCE ALL DATA IN THE - DATABASE WILL BE DESTROYED). -

    + We can now use "ant project-om" to generate our OM layer using + the adapter classes we defined above. +

    With any luck everything will compile okay and we are only a small step away from being able to use the new OM layer. The last step is to tell @@ -305,18 +245,18 @@ TurbineResources.properties:

    That is basically it. We can now modify our application to utilise the new columns via the methods defined in the OM objects we have modified. - Note that in order to access the new methods in NewappUser we need to cast + Note that in order to access the new methods in ExtendedUser we need to cast from TurbineUser thus:

    +ExtendedUSer user = (ExtendedUSer) data.getUser();]]>

    Extending TurbineUser should be relatively straightforward with the help of this information. @@ -365,20 +305,20 @@ ExtendedTurbineUser.save() is invoked. Here is an example:

    +Book book = new Book(); +data.getParameters().setProperties(book); +ExtendedUser user = (ExtendedUser) data.getUser(); +user.addBook(book); +user.save(); // !!!! book is not saved !!!!]]>

    Of course replacing the last two lines with:

    +book.setReviewedByUserId(user.getUserId()); +book.save();]]>

    - will in fact save the Rdf, this is beside the point - the other method - addRdf() shouldn't exist if it doesn't work and this is a trivial example. + will in fact save the Book, this is beside the point - the other method + addBook() shouldn't exist if it doesn't work and this is a trivial example.

    In addition to this, there is no equivalent save(dbConn) method provided