Derby
  1. Derby
  2. DERBY-4153

Document that starting with 10.5 network server will attempt to create the trace directory if it does not exist

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.6.1.0
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Starting with 10.5, Network server will attempt to create the trace directory (and any parent directories) if they do not exist. This will require that the derbynet.jar permit verification of the existence of the named trace directory and all necessary parent directories. For each directory created, the policy will require
      permission java.io.FilePermission "<directory>", "read,write"

      and the trace directory will require
      permission java.io.FilePermission "<trace directory>$

      {/}

      /-", "write"

      1. tadminadv804410.html
        4 kB
        Bryan Pendleton
      2. tadminadv804410.html
        4 kB
        Bryan Pendleton
      3. tadminadv804410.html
        4 kB
        Bryan Pendleton
      4. radminconfigdb2jdrdatracedirectory.html
        6 kB
        Bryan Pendleton
      5. radminconfigdb2jdrdatracedirectory.html
        6 kB
        Bryan Pendleton
      6. radminconfigdb2jdrdatracedirectory.html
        6 kB
        Bryan Pendleton
      7. docs.diff
        4 kB
        Bryan Pendleton
      8. docs.diff
        5 kB
        Bryan Pendleton
      9. docs.diff
        5 kB
        Bryan Pendleton
      10. ditacorrections.diff
        2 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kathey Marsden added a comment -

          The automatic creation of the trace directory was added with DERBY-3701

          Show
          Kathey Marsden added a comment - The automatic creation of the trace directory was added with DERBY-3701
          Hide
          Kathey Marsden added a comment -

          The statements made in this issue won't be totally true until DERBY-4128 is fixed.

          Show
          Kathey Marsden added a comment - The statements made in this issue won't be totally true until DERBY-4128 is fixed.
          Hide
          Bryan Pendleton added a comment -

          Now that the various code bugs have been fixed, it seems safe
          to proceed with this documentation improvement. I think that
          there are two places in the admin guide where this documentation
          would be useful: in the derby.drda.traceDirectory page, and in the
          page about how to turn tracing on.

          I tried to use the security policy lines verbatim from the JIRA description,
          but because I find Java security policy a bit confusing, I'm hoping that
          somebody who's more comfortable reading security policy syntax can
          check to see that they look accurate.

          Attached is a proposed diff for the docs, and the two revised HTML pages.

          Please let me know how they look.

          Show
          Bryan Pendleton added a comment - Now that the various code bugs have been fixed, it seems safe to proceed with this documentation improvement. I think that there are two places in the admin guide where this documentation would be useful: in the derby.drda.traceDirectory page, and in the page about how to turn tracing on. I tried to use the security policy lines verbatim from the JIRA description, but because I find Java security policy a bit confusing, I'm hoping that somebody who's more comfortable reading security policy syntax can check to see that they look accurate. Attached is a proposed diff for the docs, and the two revised HTML pages. Please let me know how they look.
          Hide
          Kim Haase added a comment -

          Thanks for working on this, Bryan. I think Rick Hillegas knows the most about security policy files, so you may have to wait till after Thanksgiving for complete info on that.

          Here are a few comments (non-technical as usual):

          radminconfigdb2jdrdatracedirectory.dita (derby.drda.traceDirectory property):

          It seems as if, for these properties, any additional information is provided in the introductory section – the Default section is used only for a terse statement of the default. Also, the new material seems to apply to an explicitly set property rather than to the default value. So it should be moved, probably to that first section. (Or maybe the Syntax section.)

          tadminadv804410.dita (Turning on the trace facility):

          I'm glad you noticed that 2 and 3 are alternatives, not sequential steps. It's good to have that corrected.

          You may have noticed that our DITA processor pays no attention to those <info> tags. It might be a good idea to make both sets into <p> tags to break up the information, because otherwise they just get munged into one paragraph.

          This isn't in the part you are adding, but you may have noticed that there seems to be a missing space on the second line of the NetworkServerControl syntax, between the > and the [. It would be great if you could put that in.

          Both topics:

          We're not very consistent about the proper font for filenames (derbynet.jar) – particularly in this book it varies from the <codeph> tag to the <i> tag to the <filepath> tag (the last is ignored by our DITA processor for the HTML frames version; it only works in the PDF and HTML book versions). So take your pick ...

          Since DIRECTORY and TRACE DIRECTORY in the security policy lines are meant to be replaceables rather than literals, you might want to follow the customary usage here and put them in lowercase and italics, and make the second into one word (tracedirectory seems most consistent with others in this section).

          You might want to put a colon at the ends of the permission lines – from other examples, this seems to be needed.

          You might also add an xref to the topic "Customizing the Network Server's security policy", tadminnetservcustom.dita.

          Show
          Kim Haase added a comment - Thanks for working on this, Bryan. I think Rick Hillegas knows the most about security policy files, so you may have to wait till after Thanksgiving for complete info on that. Here are a few comments (non-technical as usual): radminconfigdb2jdrdatracedirectory.dita (derby.drda.traceDirectory property): It seems as if, for these properties, any additional information is provided in the introductory section – the Default section is used only for a terse statement of the default. Also, the new material seems to apply to an explicitly set property rather than to the default value. So it should be moved, probably to that first section. (Or maybe the Syntax section.) tadminadv804410.dita (Turning on the trace facility): I'm glad you noticed that 2 and 3 are alternatives, not sequential steps. It's good to have that corrected. You may have noticed that our DITA processor pays no attention to those <info> tags. It might be a good idea to make both sets into <p> tags to break up the information, because otherwise they just get munged into one paragraph. This isn't in the part you are adding, but you may have noticed that there seems to be a missing space on the second line of the NetworkServerControl syntax, between the > and the [. It would be great if you could put that in. Both topics: We're not very consistent about the proper font for filenames (derbynet.jar) – particularly in this book it varies from the <codeph> tag to the <i> tag to the <filepath> tag (the last is ignored by our DITA processor for the HTML frames version; it only works in the PDF and HTML book versions). So take your pick ... Since DIRECTORY and TRACE DIRECTORY in the security policy lines are meant to be replaceables rather than literals, you might want to follow the customary usage here and put them in lowercase and italics, and make the second into one word (tracedirectory seems most consistent with others in this section). You might want to put a colon at the ends of the permission lines – from other examples, this seems to be needed. You might also add an xref to the topic "Customizing the Network Server's security policy", tadminnetservcustom.dita.
          Hide
          Bryan Pendleton added a comment -

          Thanks Kim! Those are very helpful suggestions. Attached is an updated patch proposal
          and the revised HTML pages for the two affected pages.

          Rick or Kathey or anybody else who's comfortable with using Java security
          policy to control the Network Server, can you take a quick peek at the
          HTML pages and see if the security policy portion looks reasonable?

          Show
          Bryan Pendleton added a comment - Thanks Kim! Those are very helpful suggestions. Attached is an updated patch proposal and the revised HTML pages for the two affected pages. Rick or Kathey or anybody else who's comfortable with using Java security policy to control the Network Server, can you take a quick peek at the HTML pages and see if the security policy portion looks reasonable?
          Hide
          Dag H. Wanvik added a comment -

          I wonder if there is a superfluous "/" in this line:

          permission java.io.FilePermission "<tracedirectory>$

          {/}/-", "write";

          Isn't ${/}

          - enough? "$

          {/}

          ", is a shortcut for "$

          {file.separator}

          ", so is another "/" needed/correct here?

          Show
          Dag H. Wanvik added a comment - I wonder if there is a superfluous "/" in this line: permission java.io.FilePermission "<tracedirectory>$ {/}/-", "write"; Isn't ${/} - enough? "$ {/} ", is a shortcut for "$ {file.separator} ", so is another "/" needed/correct here?
          Hide
          Bryan Pendleton added a comment -

          Good catch, Dag. I looked at the other examples, as well as at Kathey's patch in DERBY-4128:
          https://issues.apache.org/jira/secure/attachment/12405017/derby-4128_kmarsden_diff.txt
          and it's clear that the second slash should not be present.

          Updated patch and HTML files are attached.

          Show
          Bryan Pendleton added a comment - Good catch, Dag. I looked at the other examples, as well as at Kathey's patch in DERBY-4128 : https://issues.apache.org/jira/secure/attachment/12405017/derby-4128_kmarsden_diff.txt and it's clear that the second slash should not be present. Updated patch and HTML files are attached.
          Hide
          Bryan Pendleton added a comment -

          Thanks Kim and Dag for the reviews and assistance. Committed to the docs trunk as revision 885669.

          Show
          Bryan Pendleton added a comment - Thanks Kim and Dag for the reviews and assistance. Committed to the docs trunk as revision 885669.
          Hide
          Kim Haase added a comment -

          I'm really sorry, I should have caught this before. I assumed that if HTML was successfully generated, then the ant command must have run without errors – but this is not the case. There's an error for this file:

          [pipeline] [Error] tadminadv804410.dita:60:8: The content of element type "step" must match "(cmd,(info|substeps|tutorialinfo|stepxmp|choicetable|choices)*,stepresult?)".

          The problem is that there are <p> elements directly inside the step, when they need to be inside the stepxmp element.

          There's also an error for cadminconfig86869.dita, which was committed for a JIRA issue that I can't find – I must have deleted the commit message. It was somewhere around 11/23, though.

          [pipeline] [Error] cadminconfig86869.dita:37:13: The content of element type "shortdesc" must match "(ph|codeph|synph|filepath|msgph|userinput|systemoutput|b|u|i|tt|sup|sub|uicontrol|menucascade|term|q|boolean|state|keyword|option|parmname|apiname|cmdname|msgnum|varname|wintitle|tm|image)".

          There's now a <ul> in the shortdesc, which isn't allowed. The simplest solution is to do without the shortdesc and just move the whole thing, as a <p>, into the conbody.

          There's another one for the Getting Started changes that I'll mention for that JIRA.

          I think these errors may be the reason why the latest Derby documentation has not been generated since 11/30. They prevent the PDF and HTML single files from being created. I'll attach a diffs file that corrects these.

          Show
          Kim Haase added a comment - I'm really sorry, I should have caught this before. I assumed that if HTML was successfully generated, then the ant command must have run without errors – but this is not the case. There's an error for this file: [pipeline] [Error] tadminadv804410.dita:60:8: The content of element type "step" must match "(cmd,(info|substeps|tutorialinfo|stepxmp|choicetable|choices)*,stepresult?)". The problem is that there are <p> elements directly inside the step, when they need to be inside the stepxmp element. There's also an error for cadminconfig86869.dita, which was committed for a JIRA issue that I can't find – I must have deleted the commit message. It was somewhere around 11/23, though. [pipeline] [Error] cadminconfig86869.dita:37:13: The content of element type "shortdesc" must match "(ph|codeph|synph|filepath|msgph|userinput|systemoutput|b|u|i|tt|sup|sub|uicontrol|menucascade|term|q|boolean|state|keyword|option|parmname|apiname|cmdname|msgnum|varname|wintitle|tm|image)". There's now a <ul> in the shortdesc, which isn't allowed. The simplest solution is to do without the shortdesc and just move the whole thing, as a <p>, into the conbody. There's another one for the Getting Started changes that I'll mention for that JIRA. I think these errors may be the reason why the latest Derby documentation has not been generated since 11/30. They prevent the PDF and HTML single files from being created. I'll attach a diffs file that corrects these.
          Hide
          Kim Haase added a comment -

          Diffs file that corrects the DITA errors in two recently modified adminguide files.

          Show
          Kim Haase added a comment - Diffs file that corrects the DITA errors in two recently modified adminguide files.
          Hide
          Kristian Waagan added a comment -

          Kim> There's also an error for cadminconfig86869.dita, which was committed for a JIRA issue that I can't find – I must have deleted the commit message. It was somewhere around 11/23, though.

          I think the issue is DERBY- 1194 (revision 882792, 2009-11-21).

          Regarding the errors, I'll check the logs of the Hudson doc job. These docs are still only published in a non-public location, as Myrna is publishing new docs every day (I think?). I'll make it simply overwrite the published docs, such that if one process fails the other will take over. The Hudson job will only publish the docs if something has changed, and this is checked two times a week.
          I'll see if I can get the Hudson-job to fail if some of the output files are missing or if there are errors in the build log.

          As a side note, I observe that the build date of the docs built by Hudson is December 7, 2009, 12:22:30 AM (GMT+00:00). Not sure why this build process has worked, but not the other one.
          FYI, you can find the build here: http://db.apache.org/derby/docs/dev_test/adminguide/adminguide-single.html
          ("dev" becomes "dev_test")

          Show
          Kristian Waagan added a comment - Kim> There's also an error for cadminconfig86869.dita, which was committed for a JIRA issue that I can't find – I must have deleted the commit message. It was somewhere around 11/23, though. I think the issue is DERBY- 1194 (revision 882792, 2009-11-21). Regarding the errors, I'll check the logs of the Hudson doc job. These docs are still only published in a non-public location, as Myrna is publishing new docs every day (I think?). I'll make it simply overwrite the published docs, such that if one process fails the other will take over. The Hudson job will only publish the docs if something has changed, and this is checked two times a week. I'll see if I can get the Hudson-job to fail if some of the output files are missing or if there are errors in the build log. As a side note, I observe that the build date of the docs built by Hudson is December 7, 2009, 12:22:30 AM (GMT+00:00). Not sure why this build process has worked, but not the other one. FYI, you can find the build here: http://db.apache.org/derby/docs/dev_test/adminguide/adminguide-single.html ("dev" becomes "dev_test")
          Hide
          Bryan Pendleton added a comment -

          Hi Kim, thanks for catching this. I see the errors too, now that you point them out (clearly I wasn't
          reading the docs build output carefully enough).

          Is there a way for me to configure my system so that these show up as "hard" errors when I
          run commands like "ant html.ref" or "ant monohtml.adminguide"?

          I think that if the actual Ant commands failed, and did not produce the desired output, I would
          be much more likely to catch these problems during development.

          Show
          Bryan Pendleton added a comment - Hi Kim, thanks for catching this. I see the errors too, now that you point them out (clearly I wasn't reading the docs build output carefully enough). Is there a way for me to configure my system so that these show up as "hard" errors when I run commands like "ant html.ref" or "ant monohtml.adminguide"? I think that if the actual Ant commands failed, and did not produce the desired output, I would be much more likely to catch these problems during development.
          Hide
          Kim Haase added a comment -

          Kristian, thanks, it is DERBY-1194 indeed. I wonder why my build seems to fail producing the HTML single and PDF output, but yours does not. I'm sure we're using the same toolkit.

          Yes, I thought Myrna was generating new docs every day. I started to wonder when I didn't see any after 11/30.

          It would indeed be helpful, Bryan, if it would fail completely when there are dita errors, and produce a log or something. There might be something in the ant targets or properties one can set – I have trouble deciphering them, though.

          I find that the way to find errors is to wait for the output of the gen-list target, early on. If that indicates no errors, you can ignore the rest of the output. If it indicates an error, wait for the output of the debug target soon after, which gives the file and line number where the error occurs. Then control-C out of the build right away so the errors don't scroll so far you can't find them again. And then you can look in http://docs.oasis-open.org/dita/v1.0/langspec/ditaref-type.toc.html to figure out what the cryptic messages really mean.

          Show
          Kim Haase added a comment - Kristian, thanks, it is DERBY-1194 indeed. I wonder why my build seems to fail producing the HTML single and PDF output, but yours does not. I'm sure we're using the same toolkit. Yes, I thought Myrna was generating new docs every day. I started to wonder when I didn't see any after 11/30. It would indeed be helpful, Bryan, if it would fail completely when there are dita errors, and produce a log or something. There might be something in the ant targets or properties one can set – I have trouble deciphering them, though. I find that the way to find errors is to wait for the output of the gen-list target, early on. If that indicates no errors, you can ignore the rest of the output. If it indicates an error, wait for the output of the debug target soon after, which gives the file and line number where the error occurs. Then control-C out of the build right away so the errors don't scroll so far you can't find them again. And then you can look in http://docs.oasis-open.org/dita/v1.0/langspec/ditaref-type.toc.html to figure out what the cryptic messages really mean.
          Hide
          Bryan Pendleton added a comment -

          I confirmed that Kim's follow-up patch removes the [Error] lines from the gen-list portion of the
          build in my environment, and committed it to the docs trunk as revision 888226.

          I'll leave the issue open until we get confirmation of a clean build to the web site.

          Show
          Bryan Pendleton added a comment - I confirmed that Kim's follow-up patch removes the [Error] lines from the gen-list portion of the build in my environment, and committed it to the docs trunk as revision 888226. I'll leave the issue open until we get confirmation of a clean build to the web site.
          Hide
          Bryan Pendleton added a comment -

          (re-)resolved. The follow-on patch seems fine, and the docs build
          to the web site seems to be working now.

          Show
          Bryan Pendleton added a comment - (re-)resolved. The follow-on patch seems fine, and the docs build to the web site seems to be working now.

            People

            • Assignee:
              Bryan Pendleton
              Reporter:
              Kathey Marsden
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development