1. jxta-guide

PSE example very difficult to use and understand


    • Type: Improvement Improvement
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: current
    • Fix Version/s: milestone 1
    • Component/s: www
    • Labels:
    • Environment:

      Operating System: All
      Platform: All

    • Issuezilla Id:


      Hi folks!

      For considerable time I am struggling with the PSE example from the tutorial
      (with limited success) and I would like to make some suggestions to improve its
      usefulnes. Some observations:

      • The tutorial gives me the impression of being both close to the implementation
        and often looks at the use of things within Jxta. It frequently gives me the
        feeling that many parts address more the people building Jxta itself rather than
        the ones using it. In other words, the documentation gives a lot of small-scale
        details (about parameters and how Jxta is doing things under water), but not so
        much about why a user would want or need to do it. Also, many things in the
        examples look very simple and trivial (showing just one single
        activity/function), but as soon as a user wants to do something slightly
        non-trivial beyond copy/pasting these code sniplets, (s)he is left alone without
        guidande. A high(er)-level description and examples of the 'general layout' of a
        Jxta application might help here. Something in between the 'set up a pipe' and
        'read the code of myjxta' or 'jxta-shell commands'. Off course, reading all this
        code eventually may enlighten most people - but at the cost of a very steep,
        long, and often frustrating learning curve.
      • The documentation in the source code (of the PSE example) does not help with
        the previous issue.
      • Starting the application 'to get a feel' for what should happen when is of
        little help because nothing is explained about how to use the app.
      • Javadoc in SwingUI states that everything is enabled by design (to allow
        playful souls to explore all the possibilities how things can go wrong). This is
        fine and usefule if somewhere the not-so-curious user gets a script for the
        good path.
        You may want to look at it this way: the setup of the peers, generation of
        certs, exchanging them, signing them acquiring and changing roles etc. is a
        (complex?) protocol. And this protocol is not explained or vizualized enough in
        Chap9/10 and explicitly hidden in the gui (everything always enabled).
        I do not want to 'discover' the correct protocol sequence by trial and error.

      Lots of googling brought me to this mail exchange between "Bruno" and "Mike",
      which was vital for me to get the first useful thing from the PSE exampel:

      What I am missing in the tutorial (Ch 9/10) is what Bruno calls 'the second
      document', and Mike speculates about a narrative/usage script/animated movie.
      This mail exchange is from 2005, thus the idea has apparently been abandoned or
      drifted out of sight.

      In order to keep the required amount of work to a minimum I would like to
      suggest to add a slightly reworked/extended version of Bruno's script.
      --Quote-(numbers added by quoter)--
      1- First become a peer group owner using the hardcoded keystore value of
      <password> and self invitation passord of <topsecret>
      2- From the Peer group Owner role, assume the Administrator role, and create an
      invitation for a peer to join.
      3- Start another instance of the demo and try joining the pse group by using the
      Administrator’s invitation.
      4- Start a fresh demo and have a “psePeerGroup� applicant generate a certificate
      and CSR.
      5- From the administrator or owner role sign the CSR into a signed certificate.
      6- Have the “psePeerGroup� applicant join the “psePeerGroup� by importing the
      signed certificate.

      The first part of the scenario shows the owner of a PSE-secured peer group
      accessing his/her group (step 1).

      Scene two has the owner send an invitation (for which level of access? how to do
      other types of access?) to user B.
      It would be good to indicate which kind of information the Owner should have
      about B to do that.

      Scene three (I think) should show how an existing user C can get her (existing)
      certificate validated to join the peer grop

      Scenes one and two (steps 1..3) work relatively well. What should be added here
      is how to get to the Administrator tab (Bruno commented on that as well), why
      you have to get that role in the first place if the "owner", which you
      apparantly become first, should have all the rigths already.

      Scene three (step 4) I have not been able to follow, yet. The APP does not allow
      me to generate a certificate without using the 'topsecret' password, which user
      C would and should not have.

      It may be interesting to add more scenes (if available), for instance:

      • how would I go about having the 'request to join peer group' exchanged with
        Jxta (A needs to be around, C starts, contacts A in some way not requiring the
        certs, A decides whether to trust what C sent, signs and sends it back).
      • how can Owner/Admin issue temprorary certificates
        I would also appreciate some outline (or pointers to relevant documents) about
        how to work with keystores in java.



        There are no comments yet on this issue.


          • Assignee:
          • Votes:
            0 Vote for this issue
            0 Start watching this issue


            • Created: