packaging submission

[Mike Southgate]

I'm putting the finishing touches on my userguide.html file. In my instalation section I need to cover how to install the server and the client. Now, there are two ways of doing this, running it directly from the jar executable and extracting all the files and then running rom where you put it. In either case some use of the jar tool is required. To what extent do I need to document how to use the jar tool to get the files or execute the application?
ms

[Patrick Cobbett]

I'm putting the finishing touches on my userguide.html file. In my instalation section I need to cover how to install the server and the client. Now, there are two ways of doing this, running it directly from the jar executable and extracting all the files and then running rom where you put it. In either case some use of the jar tool is required. To what extent do I need to document how to use the jar tool to get the files or execute the application?
ms
Hi Mike, i would be curious to hear what other people have to say but this is my opinion. Seeing as the submission is packaged as a JAR file, we can safely the assume that the user should know how to extract files. Giving instructions on how to extract files from a JAR file in the readme.txt isn't much help if they can't even unjar the submission to get to readme.txt!
Certainly, you should explain how to set the classpath to point to your jar files. Also, you should provide command line instructions to execute the jar files, for example:
c:\INSTALLATION_DIR\java -jar server [port]
You should also include instructions for running the RMI registry if required.
I know it's tough deciding how much information to provide. No doubt the marker will know how to do most of the instructions we supply anyway. But the instructions should be sufficiently complete for any one to run and use it. How stupid we are supposed to assume that most people are, i'm not sure.
hope this helps

[Andrew Monkhouse]

Hi Patrick & Mike

Now, there are two ways of doing this, running it directly from the jar executable and extracting all the files and then running rom where you put it.

I handled this by saying that extracting the class files from my jar files was unsuported This meant that I did not have to document the jar tool at all.
Where I did document anything provided by Sun (for example: the Java runtime itself), I only gave very brief descriptions of what to do to run the way I intended, then pointed them at the Sun documenation for more information.
Mike, does the Contractor's assignment require you to allow the user to run using the extracted class files? I thought you only had to provide the runme.jar file?

we can safely the assume that the user should know how to extract files

Can we? I have worked in companies where end users were not allowed to do anything on their PCs. Even to get a new printer driver installed, I had to call the support center and get someone to come over to my desk and install it. In such an environment, it is possible that the administrators would unpack the submission jar file, and dump it on my machine, and then I can just work with the files that I have been given. No need for me to know anything about the jar file.
I know that this is a bit far fetched, since the examiner has to be able to intelligently examine our code, so they must know something about Java (we hope :roll: ). But the instructions for the Fly By Night Services assignment explicitly told us to spell things out for the user ("do not just say what needs to be done; provide instructions on how to perform the setup"). There does not appear to be a similar requirement in the UrlyBird assignment.
If you are going to allow people to unjar your jar files, then I believe you are going to have to be explicit in your instructions, so that a dumb user can follow them. But don't try and rewrite the Sun documentation: just document what is needed, then refer them to Sun for more information.

Certainly, you should explain how to set the classpath to point to your jar files.

If you only have one executable jar file, then you don't need to set the classpath - one less thing to document
Regards, Andrew

[Billy Tsai]

I put screen shots in the html file showing step by step of how to run the program

[Patrick Cobbett]

Hi Andrew,
How come you only have one executable jar? Didn't you use one for the client and one for the server, or are they distinguished at the command line?
The requirements for FBNS that you quoted was describing environmental setup.

If any environmental setup is required, do not just say what needs to be done; provide instructions on how to perform the setup.

I'm not sure if describing how to use the JAR tool goes under environmental setup. Won't hurt though to include it, i may well do so myself.
Also you say that if there is only one jar file then it doesn't need to be added to the class path. The instructions say that the program should run what ever directory it is installed in. If the jar file is located anywhere but the class path then the class path will need to point to it. Also, why does it make a difference whether there is one or two jar files?
For FBNS, do we have to support execution with the class files aswell as executable jar files?
My last question is this. Bearing in mind that i am setting the class path.. in windows 98 the class path can be set with:
set classpath=%classpath%;NEW_DIR
But i'm using a different computer now to when i started, and in windows 2000 i understand it's set differently. Any one know how this is done? I thought i could avoid this by documenting (as was explicitly required) that i was using Windows 98. However, no one seems to be taking any chances so i don't think i will either!
Also, Andy, how long ago did you submit? You expecting your results soon?
good luck

[Andrew Monkhouse]

Hi Patrick

Andrew: If you only have one executable jar file, then you don't need to set the classpath - one less thing to document
Patrick: How come you only have one executable jar? Didn't you use one for the client and one for the server, or are they distinguished at the command line?

Mike is doing the Contractors assignment (from memory), so he should only have one jar file.
Yes, I had one for the client and one for the server. But each jar had all the classes needed to run the appropriate application - so I did not have to have either in my classpath.

Patrick: The requirements for FBNS that you quoted was describing environmental setup.

Yes. But I feel that if this is the level of information required for one section, then it could apply to all sections. But I am accept that it may be a bit of a leap for me

Patrick: Also you say that if there is only one jar file then it doesn't need to be added to the class path. The instructions say that the program should run what ever directory it is installed in. If the jar file is located anywhere but the class path then the class path will need to point to it.

No, you should be able to run your application from another directory even without the jar file being in the classpath. Try it and see. I have certainly used command lines such as:

c:\temp> java -jar z:\scjd\client.jar

And it worked perfectly without manually setting the class path.
For those who want to go a step further: try printing your class path from within the java program within the jar file. You should find that when you type "java -jar ..." at the command prompt, Java automagically adds the fully qualified path to the jar file into the class path (hint: if you want to automagically find the database file to present to the end user as a default, you can use this path as a starting point).
Now, having hidden this hint in the middle of an unrelated topic, on a slow weekend, will anyone see it?

Patrick: Also, why does it make a difference whether there is one or two jar files?

Because if you are using two jar files, then you will need to set the classpath.

Patrick: For FBNS, do we have to support execution with the class files aswell as executable jar files?

I didn't
The instructions tell us that we may use jar files to package parts of our submission if we want to. I did, and then, had some comment that the code would all work if it was extracted from the jar file, but it would not be supported in this mode.

Patrick: My last question is this. Bearing in mind that i am setting the class path.. in windows 98 the class path can be set with:
set classpath=%classpath%;NEW_DIR
But i'm using a different computer now to when i started, and in windows 2000 i understand it's set differently. Any one know how this is done?

I am no longer using any Microsoft software, so my comments here are not definitive.
Just looked in the Tomcat startup script, and it sets it like so:

set CLASSPATH=%CLASSPATH%;%JSSE_HOME%\lib\jcert.jar;%JSSE_HOME%\lib\jnet.jar

Nothing special done for different versions of Microsoft Windows.
But the startup scripts do have the following in them as well:

if "%OS%" == "Windows_NT" setlocal

Windows 2000 is based on NT, so it might set the OS to Windows_NT (you can check easily enough), and I have no idea what the setlocal command does.
If it is any help, under Linux the equivalent is:

 
CLASSPATH="$CLASSPATH":"$JSSE_HOME"/lib/jcert.jar:"$JSSE_HOME"/lib/jnet.jar

Also, Andy, how long ago did you submit? You expecting your results soon?

Sorry, you used up your last question with the Classpath issue
I submitted on the 29th May, then went for a week away to ensure that I didnt check for my results 100 times a day. When I got back, I found that the results had been posted on the 31st May (something of a record!). You can read the grisly details here.
Regards, Andrew (who just got caught with the bug where an edit of a post with both quote and code blocks will cause the quotes to be lost )
[ July 27, 2003: Message edited by: Andrew Monkhouse ]