How does one go about documenting complex tools?

I am now writing Java code (hooray for me) and playing around with Ant as part of my work. It isn't entirely tout le monde type stuff but it isn't anything spectacular. Yet. So, to my (much disappointed) audience, I ask, how does one go about learning about any system that is full of things one has little idea of? I learn by trying things and documenting them... but where do I start? From top down? From bottom up? What if I don't know where the bottom is?

Also what are the rules about changing someone else's work? Do you just go ahead and change things willy-nilly? Is there such a thing as respecting someone else's creations and working around them?

Oh, so many questions!

I win!

Damn you eclipse, you drove me nuts for a while. DAMN. I spent good chunks of my nights and weekends fighting you. I was about to give up and go back to Windows Vista. Damn. I need to update all my newly found Goran Bregović music anyway. Quite a few people mused about what it could be. They were right, somewhat. So, what was it in the end? Lets see.

I install ubuntu. I have no idea what version... The installer decided to install x86_64. Why? Well, I have a 64-bit compatible chip. Well, when you go to eclipse.org and download eclipse, they figure out somehow that I am running a 64-bit version of the OS and let me download the 64-bit version of eclipse. I didn't notice. I installed eclipse. All is good. Or so I thought. I try and fire it up. Nothing happens except for the error. You would think that something so large would log something somewhere. No such luck. I looked in the obvious place: ~/.eclipse. I ran eclipse -clean. No luck.

I searched google. Ubuntu docs say to use apt-get install eclipse. I tried that. No luck. And it installed all sorts of gcj nonsense that I don't really want. I want Sun JDK. More searching ensued. Hours went by. I watched Borat along the way. Its just as much fun the second time around (I watched it the first time on my second trip to Washington DC). Yet more searching. I checked all sorts of things. I tried to launch it manually. You know with all the 50 arguments it needs to start. Still no luck. And quite frustratingly, no log file that says 'Oh by the way, you need blah' or 'you are missing something X that I need in order to run properly'. Grrrrrr.

I ended up searching for stuff specific to Ubuntu and Eclipse and Linux and somehow I ended up on an eclipse.org page. They mention a log file in there too. I didn't find one anywhere. But it was at that point that I ran a uname -a. I had previously also tried to try and start eclipse using Java 1.5 (release 15) but still no luck. Well, uname -a told me I was running x86_64. I kept going. I downloaded the x64 version of Sun's JDK. Hmmm. I installed it. It wanted to overwrite stuff in the 32-bit JDK folder. I decided to wipe out all the 32-bit JDKs. I installed the 64-bit JDK. I ran ./eclipse once more. Would you believe it, I was asked to pick a workspace!

So much for all that checking. Silly me, I should have checked all that before I went about searching google. One issue I still have though is: if eclipse won't start, how the <deleted expletive> am I supposed to know that it is a 64-bit version of eclipse and requires a 64-bit JVM (or a modified start process with a -d32 flag or something)?

Oh well, so much for all that. I have eclipse running. Let that be a lesson to all of you. 64-bit computing is a pain in the ass.

Getting Eclipse to work in Linux

Getting Eclipse to start in Linux is a nighmare. You can't just double click on stuff like in Windows. Right now, the error I get when I try and start eclipse, I get the error:

JVM terminated. Exit code=13
/usr/local/jdk1.6.0_05/bin/java
-Dosgi.requiredJavaVersion=1.5
-Xms40m
-Xmx512m
-jar /usr/local/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118.jar
-os linux
-ws gtk
-arch x86_64
-showsplash
-launcher /usr/local/eclipse/eclipse
-name Eclipse
--launcher.library /usr/local/eclipse/plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.0.3.R33x_v20080118/eclipse_1023.so
-startup /usr/local/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118.jar
-exitdata aa8030
-vm /usr/local/jdk1.6.0_05/bin/java
-vmargs
-Dosgi.requiredJavaVersion=1.5
-Xms40m
-Xmx512m
-jar /usr/local/eclipse/plugins/org.eclipse.equinox.launcher_1.0.1.R33x_v20080118.jar

I launched the thing using
/usr/local/eclipse/eclipse -vm /usr/local/jdk1.6.0_05/bin/

Lets see how it goes... I am not giving up yet.

Sorry, I promise to do better

To my dear mentor and to my team mate... I do apologise for my lack of working. Its past 1am and I am up. But I assure you I have an ace up my sleeve now, I promise. What is it? Ubuntu 8. Installed via Wubi.

All I need to do now is apt-get install eclipse... okay, well maybe that was a dumb thing to say. I'll do in manually of course. But I assure you, now that I have a happy development environment without any crazy ass security (aside from selinux, but that's another story). I will be back soon, I promise. In the meantime, join the revolution, join Mao and step on the Tibetans... Not.

Nemo me impune lacessit as the good lads from the Black Watch would say. BTW, little known trivia fact; I do indeed own an 18 oz Black Watch kilt with highland hose and flashes... no sporran though. Yet.

Your next assignment is...

I have a mentor type character who gives me projects to do on a regular basis... and then messages me asking for it. My next assignment then was to do setup Hibernate and be able to do CRUD on an object.

I had a couple of problems getting going related to my box itself. For whatever reason, it takes ages to unzip files. I needed Ant, HSQL DB and the hibernate jar files... and it took painfully long.

I've been working for a while on a simple example based on the Hibernate Reference Documentation but I've run into an issue with the List, eclipse seems to choke on it. I get an error that says:

List is a raw type. Reference to generic type List <E> should be parameterized

The List it mentions is from

import java.util.List;

The line in question is:

List stuff = psm.listPersistedStuff();

and the function declaration is:

private List listPersistedStuff()

I think some post Java 5 generics stuff is getting in the way. I've never used generics before and I guess I'll be learning quickly :). But if anyone knows what's wrong here, I would appreciate a pointer or two. Some of the Sun forums talk about suppressing the warnings in the function, but they also suggest that is a poor way to get around the problem. So I am not going to.

My JDK in case anyone is wondering is 1.6.

Build and Manage Clickpaths

Build a Clickpath:

1. The user has the ability to build a clickpath based on an existing set of functions
1. In order to successfully build a clickpath, the user has to fill all the required fields. The required field are as follows:
1. The user should be able to select an Application Name
   
2. The user should be able to select a Version
3. The user should be able to select a System
4. The user should be able to select a Sub-system
5. The user should be able to enter a Use Case Name
   
6. The user should be able to select an Actor
7. The user should be able to select a Function(s)
1. The user should have the ability to search for functions via Basic Search or Advanced Search as described below
2. The user should be able to choose only one function at a time in order to add the functions in order
   
2. The user should have the option to add any notes or comments related to the clickpaths
2. Once the clickpath has been successfully created, the user will receive an inline verification, with the clickpath information (application name, version, system, sub-system, actor, use case name, and functions) as well as the clickpath ID generated by the system.
   

Basic Search

1. The user has the ability to search for clickpaths using one of the four following criteria:
   
1. The user can search for a clickpath by entering a clickpath ID
2. The user can search for a clickapth by entering a use case name
3. The user can search for a clickapth by selecting a sub-system
4. The user can search for a clickpath by selecting an actor
   
5. The user can choose "contains", "equals", or "start with" option when searching for clickpaths.
   

Advanced Search

1. The user has the ability to perform a complex search based on multiple criteria
1. The user can choose "contains", "equals", or "start with" option when searching for clickpaths
   
2. The user can perform a search on any of the following fields:
   
1. Application Name
2. Version
3. System
4. Sub-system
5. Actor
6. Use Case Name
7. Function Name
8. Status Message Name (from a function)
   
3. The user can perform a complex search by using "AND" or "OR" operator
   

Edit Clickpath

1. The user has the ability to edit a clickpath that already exists in the system
1. The user will search for the clickapth using either the Basic Search or the Advanced Search
2. The user is able to select the clickpath he wants to edit
3. The user will be able to edit the following fields:
   
1. Application Name
2. Version
3. System
4. Sub-system
5. Use Case Name
6. Actor
7. Functions
1. The user will have the ability to re-order the already chosen functions
2. The user will have the ability to remove functions from the list
3. The user will have the ability to add new functions to the list
8. Any additional notes or comments
2. Once the clickpath has been successfully modified, the user will receive an inline verification, with the clickpath information: application name, version, system, sub-system, actor, use case name, clickpath ID and functions

Remove Clickpath

1. The user has the ability to remove a clickpath(s) from the system
1. The user will search for the clickpath(s) using either the Basic Search or the Advanced Search
2. The user has the ability to select the clickpath(s) from the search results and choose to remove them

Sample Java code for fun

I was given a set of requirements that I can quote:

write me a program that reverses the order of a sentence

Does that mean the sentence is reversed in terms of each letter? Or is it each word? Or is it each word reversed? Well, I did one of each for kicks.

So here is each piece. Enjoy.

package com.blogpost.revolutioniselouder;


public class Main
{
/**
* This function reverses all letters in a string
* @param s string to reverse
* @return a string with all letters in reverse order
*/
public String reverseAllLetters( String s )
{

StringBuffer stringToReturn = new StringBuffer( s );

// Use the StringBuffer's reverse function to reverse all letters
stringToReturn = stringToReturn.reverse();

return stringToReturn.toString();

}

/**
* This function takes a string and a separator, splits the string and then individually
* reverses each of the letters. Keep in mind that punctuation will be reversed as well
* _if_ it is not used as the separator.
* @param s String to reverse words
* @param separator the pattern to split the string by
* @return a String with every word reversed. For example if the String is 'car cat', the returning
* reult is 'rac tac'.
*/
public String reverseLettersInAWord( String s, String separator )
{

StringBuffer stringToReturn = new StringBuffer();
// split the string using separator passed in
String[] splitStrings = s.split( separator );

/* cycle through the split strings, reverse their letters, re-generate string */
for ( int i = 0; i < face="courier new"> {

stringToReturn.append(reverseAllLetters( splitStrings[ i ] ) );
stringToReturn.append( separator );

}
return stringToReturn.toString();

}

/**
* Reverses Words in a string. If a string is 'car cat', the reversed string owuld be
* 'cat car'
* @param s String to reverse words
* @param separator the pattern to separate the words by
* @return String with words in reversed order
*/
public String reverseWords( String s, String separator )
{

StringBuffer stringToReturn = new StringBuffer();
String[] splitStrings = s.split( separator );

/* Take the last word, add it to the beginning of new string and continue until the split original string is parsed through */
for ( int i = splitStrings.length; i > 0; i-- )
{
stringToReturn.append( splitStrings[ i - 1 ] );
// add separator, so string looks normal
stringToReturn.append( separator );
}
return stringToReturn.toString();

}

/**
* Try some simple testing with one string for each string.
*/
public static void main( String [] args )
{

String s = "Never in the field of human conflict was so much owed by so many to so few.";
Main m = new Main();
System.out.println( m.reverseAllLetters(s) );

System.out.println( m.reverseLettersInAWord( s, " " ) );

System.out.println( m.reverseWords( s, " " ) );

}

}

Hopefully, the output will be proof enough:

.wef os ot ynam os yb dewo hcum os saw tcilfnoc namuh fo dleif eht ni reveN
reveN ni eht dleif fo namuh tcilfnoc saw os hcum dewo yb os ynam ot os .wef
few. so to many so by owed much so was conflict human of field the in Never

Lets hope that meets the requirements.

Add and Manage Functions.

Add a Function:

1. The user will be able to add functions into the database.
1. In order to successfully add a function, the user has to fill all the required fields. The required field are as follows:
1. The user should be able to select an Application Name
1. If the application name does not exist on the list, the user will have the ability to add a new application name.
   
2. The user should be able to select a Version
1. If the version does not exist on the list, the user will have the ability to add a new version.
   
3. The user should be able to select a System
1. If the system does not exist on the list, the user will have the ability to add a new system.
   
4. The user should be able to select a Sub-system
1. If the sub-system does not exist on the list, the user will have the ability to add a new sub-system.
   
5. The user should be able to enter a Function Name
   
6. The user should be able to select an Actor
1. If the actor does not exist on the list, the user will have the ability to add a new actor.
7. The user should be able to enter a Status Message
   
2. The user should have the option to add any notes or comments related to the function
2. Once the function has been successfully added, the user will receive an inline verification, with the function information: application name, version, system, sub-system, function name, actor, status message.
   

NOTE: we are assuming users will not entering helper function.


Basic Search

1. The user has the ability to search for functions using one of the four following criteria:
   
1. The user can search for a function by entering a function name
2. The user can search for a function by entering a status message
3. The user can search for a function by selecting a sub-system
4. The user can search for a function by selecting an actor
5. The user can choose "contains", "equals", or "start with" option when searching for functions.
   

Advanced Search

1. The user has the ability to perform a complex search based on multiple criteria
1. The user can choose "contains", "equals", or "start with" option when searching for functions
2. The user can perform a search on any of the following fields:
   
1. Application Name
2. Version
3. System
4. Sub-system
5. Actor
6. Function Name
7. Status Message
3. The user can perform a complex search by using "AND" or "OR" operator
   

Edit Function

1. The user has the ability to edit a function that already exists in the system
1. The user will search for the function using either the Basic Search or the Advanced Search
2. The user is able to select the function he wants to edit
3. The user will be able to edit the following fields:
   
1. Application Name
2. Version
3. System
4. Sub-system
5. Function Name
6. Actor
7. Status Message
8. Any additional notes or comments
2. Once the function has been successfully modified, the user will receive an inline verification, with the new function information: application name, version, system, sub-system, function name, actor, status message.

Remove Function

1. The user has the ability to remove a function(s) from the system
1. The user will search for the function(s) using either the Basic Search or the Advanced Search
2. The user has the ability to select the function(s) from the search results and choose to remove them

Questions, questions

I have been trying to do use Eclipse and do some things with it (like use Acceleo) but have had very little luck with it. I have an Eclipse project with nothing in it.

I also have questions on stuff I store in the database and how to get them out of there. I wonder if there is a way to write an object to the database and read it out as is (and also take parts of it out as well); I recall hearing that as a feature in SQL Server 2008.

What options exist for source control? I am wondering if there is some really light-weight source control thing that integrates into Eclipse?

I'll blog more as I can find them, but for now, I have to go do other stuff...

The work begins... with a roadblock

I want to use MySQL Workbench. I install the workbench and MySQL 5. I am having a problem with MySQL's instance manager. I get the error message below:


So why am I getting this weird error message? How am I supposed to start MySQL even? These are things I have to answer. This blog entry looks helpful, so I'll give that a go.

But what of the plan, my fearless leader?

Yes, the plan. The master plan. What is it? The grand vision will be laid out here. I'll work on the details later. So, what is this thing? Well, it involves a database. It involves a webpage. I click on things. Stuff gets pulled out of the database. I type some stuff in the webpage. Stuff gets written to the database. That's the big picture.

Obviously, that isn't very much detail. I already knew that from my previous post. Even though I was the father of some great ideas. So let me elaborate, but slightly.

Lets see, language to use: Java. I've used it before. It makes sense. Its popular. _Hopefully_ knowing it better will let me improve and move on. The opportunity cost here is that I am giving up the chance to learn something else... but I will live with that for today. I am guessing this will be the application tier.

Lets see, I need a database. Someone suggested MySQL. So I went for it. I originally thought of using Oracle or SQL Server. But I'll use Connector/J, use JDBC and learn something out of that.

The so called webpage? Well, I say we use tomcat 6. Should help to fiddle around with that. I want to create JSPs on there to manipulate the data I want to get out. So far so good?

What am I going to use to create this? I am going to use an IDE. I've used NetBeans before. Never used Eclipse. Have wanted to for a while. So I will.

I am sure I've forgotten things here, but I feel good right now. So I'll stop.

Welcome to the revolution... I think

So, what is this? Well, to put it simply, this is an exercise in learning. Maybe re-learning even. To grow, to prosper and to make me a better person. Vague enough for you?

I intend this space to be used to explore technology projects that I want to pursue in my free time; to learn, collaborate and perhaps be of some use to someone else one day... lofty goals, yes. Achievable ones? Yes.

So, let us take the plunge and become part of this revolution. Oh and P.S. I am taking up the blogging culture. Loud enough for you?