(→Unpacking the Club Strings Library (provided)) |
(→Unpacking the Core Library) |
||
Line 153: | Line 153: | ||
Now that you are inside the "mess" directory, let's unpack the '''po-bank-core''' and '''po-bank-textui''' sources ('''do not''' compile): | Now that you are inside the "mess" directory, let's unpack the '''po-bank-core''' and '''po-bank-textui''' sources ('''do not''' compile): | ||
− | tar xvfj po-bank-core- | + | tar xvfj po-bank-core-201308300030.tar.bz2 |
− | tar xvfj po-bank-textui- | + | tar xvfj po-bank-textui-201308300030.tar.bz2 |
This will have created the two following directories inside the "mess" directory: | This will have created the two following directories inside the "mess" directory: | ||
− | po-bank-core- | + | po-bank-core-201308300030 |
− | po-bank-textui- | + | po-bank-textui-201308300030 |
<font color="brown">''Do not change the current directory from "mess"''.</font> | <font color="brown">''Do not change the current directory from "mess"''.</font> |
The bank application is very small and simple. Nevertheless, it already incorporates all major components needed for a larger application.
The following is a quick guide to start your project from the Bank sources.
You may want to also take a look at the CVS Crash Course.
The following are the components of the bank application (these are the 2010/2011 editions):
More (official) information: https://fenix.ist.utl.pt/disciplinas/po6/2013-2014/1-semestre/projecto/desenvolvimento-do-projecto
Each package includes a makefile to compile and build the corresponding JAR archive. Note that the makefiles assume that all JAR dependencies reside in /usr/share/java (linux installation -- other environments may, and indeed should work, but are not covered in this text).
The bank application has a similar structure to the one needed for the OOP course programming project (but... be careful).
This first part documents the steps needed to obtain a runnable version of the bank application.
It is important to understand each step and the role played by each library in the final project. This way, you can make surgical changes to the code and transform it in useful ways (e.g., to reuse it in similar projects).
First and foremost, note that this library does not need to be changed. If you think it does, either you found a bug (unlikely, but you never know...), or you are doing something wrong. In either case, seek help before proceeding into certain oblivion.
To unpack, compile, and install the user interface library, do the following:
tar xvfj po-uilib-201308300030.tar.bz2 cd po-uilib-201308300030 make
If you are unlucky enough not to have GNU tar, try it this other way:
bzcat po-uilib-201308300030.tar.bz2 | tar xvf - cd po-uilib-201308300030 make
Note that there is no "make install" command (the makefiles don't have that rule). To install, simply copy the po-uilib.jar file to some directory. Remember the name of this directory: we will simply call it JAVADIR. All makefiles assume that this directory is /usr/share/java (the default place for JAR files in Linux). However, you can put JARs anywhere. To change the place, simply do:
JAVADIR=/some/other/directory/i/prefer/to/use/for/my/jars
This line can be set directly in the makefiles. Note that you will need writing privileges in that directory. If you have an RPM-based distribution, the following repository has up-to-date versions (example for openSUSE 11.4):
Other distributions may become supported (but remember: tests are run only on openSUSE 12.3). Check:
Similarly, to unpack, compile, and install the strings library, do the following:
tar xvfj po-bank-support-201308300030.tar.bz2 cd po-bank-support-201308300030 make
Note that po-bank-support.jar depends on po-uilib.jar: you will have to set JAVADIR in the makefile (as explained above).
As before, install it by copying po-bank-support.jar to JAVADIR (the place where you put po-uilib.jar).
In the OOP course project, different support libraries are, of course, needed. The role played by po-bank-support.jar in the bank application will be played by calc-support.jar in the calc applications. Note that you won't reuse any of the bank application's support classes and will simply replace one library for another.
Similarly, to unpack, compile, and install the core library, do the following:
tar xvfj po-bank-core-201308300030.tar.bz2 cd po-bank-core-201308300030 make
As before, install it by copying po-bank-core.jar to JAVADIR (the place where you put po-uilib.jar and po-bank-support.jar). We go through the installation procedures because we assume that the core can be used by any number of applications.
Note that this is the main library, i.e., the one containing classes that make a bank application and all the corresponding functionality. Very little will be directly reusable in the OOP course project, but the relationship between this library and the others in an application remains the same across applications. This means that a different core will exist in some other application, but its role will be the same played in the bank application by po-bank-core.jar.
Note that po-bank-core.jar does not depend on any other library but itself (in the sense that it does not depend on the user interface libraries -- even though it might depend on libraries providing specific functionality, such as tax computations). This is exactly the same for any other application (the core is always autonomous). Thus, if you need extra dependencies, you are (most likely) doing something wrong and should seek informed help.
Similarly, to unpack, compile, and install the user interface library, do the following:
tar xvfj po-bank-textui-201308300030.tar.bz2 cd po-bank-textui-201308300030 make
Note that po-bank-textui.jar depends on all the previously presented libraries: you will have to set JAVADIR in the makefile (as explained above).
As before, install it by copying po-bank-textui.jar to JAVADIR (the place where you put po-uilib.jar and the others). We go through the installation procedures because we assume that the core can be used by any number of applications.
Note that this library, in addition to containing the user interface classes needed to implement the interaction with the user, in particular, containing the classes that implement the Command pattern, also contains the application class itself, i.e., the class containing the main function. In a sense, this is the face of the bank application.
Assuming that you put all the JAR files in JAVADIR (representing here a shell environment variable), the Bank application can be run with the following command (App is the class containing the main function and "BPO" is the bank's name):
java -cp $JAVADIR/po-uilib.jar:$JAVADIR/po-bank-support.jar:$JAVADIR/po-bank-core.jar:$JAVADIR/po-bank-textui.jar App BPO
Alternatively, define the CLASSPATH environment variable and run the application this other way:
export CLASSPATH=$JAVADIR/po-uilib.jar:$JAVADIR/po-bank-support.jar:$JAVADIR/po-bank-core.jar:$JAVADIR/po-bank-textui.jar java App BPO
Now that we have understood how to compile and run the Bank application, we will see how to reuse the code to jumpstart some other project. The basic strategy will be to change names (of packages and classes) until the result resembles the desired outcome.
First, note that all classes in the Bank application are in the bank package or in one of its subpackages (regardless of one package being split across multiple libraries -- e.g., the po-bank-support and the po-bank-textui libraries both contribute code to the bank.textui package and its subpackages).
Second, remember that the strings library will be completely replaced and we will not have to worry about adapting it. Also, note that the new strings library will control how the textui library's code is written/adapted (it directly depends on the string production facilities of the strings library).
Third, note that even though there are parallels, most likely, the core library will have to be mostly rewritten. Here we are not trying to force classes to perform in different scenarios, but rather trying to show how project have similar structures. Nevertheless, it may happen that some concepts are close enough to be adaptable.
In the following examples, we will assume that the new project intends to build the Club application. Its main package will be called club. Since this is probably an application about clubs, we will assume that the Club class exists and is similar to the Bank class, not in itself, but in the role it plays in the application (this means that we will transfer responsibilities, such as answering commands from menus, from one class to the other). Other parallels included the club.textui package, and so on.
Try it, just to be sure you can do it:
tar xvfj po-club-support-201310152029.tar.bz2 cd po-club-support-201310152029 make
Ok? Good.
Copy it to JAVADIR (if you went through the first part, po-uilib.jar should already be there).
As with po-uilib.jar, if you have an RPM-based distribution, the following repository has up-to-date versions (example for openSUSE 12.3):
Other distributions may become supported (but remember: tests are run only on openSUSE 12.3). Check:
Note that the support library may be called something else, such as calc-support-201309011814.tar.bz2 (i.e., only the outer name is different, but the JAR file will have the expected name).
Do:
mkdir mess cd mess
Now that you are inside the "mess" directory, let's unpack the po-bank-core and po-bank-textui sources (do not compile):
tar xvfj po-bank-core-201308300030.tar.bz2 tar xvfj po-bank-textui-201308300030.tar.bz2
This will have created the two following directories inside the "mess" directory:
po-bank-core-201308300030 po-bank-textui-201308300030
Do not change the current directory from "mess".
Now rename all files, so that the "Bank" part becomes the name corresponding to your project ("Club").
If you have zsh:
rename Bank Club ./**/*(.)
Or, if you have the other rename (but still with zsh):
rename 's/Bank/Club/g' ./**/*(.)
If you have other shell variants (also good for zsh), try these:
find . -type f -print -exec rename Bank Club {} \;
Or:
find . -type f -print -exec rename 's/Bank/Club/g' {} \;
If all went well, all the "Bank" bits in the file names should now read "Club".
Do the same for directories (since they correspond to packages, the change should be from "bank" to "club"). Be careful in this step: since there are directories whose name is going to change, recursive procedures (such as the ones above) may fail and several tries will be needed until all directories have the correct name. If in doubt, do it by hand.
Now that the outside is changed, lets concentrate on the inside. For this, we will use grep (GNU grep, if you must know) to find all occurrences of bank, Bank, and BANK, to change them, respectively, into club, Club, and CLUB. This procedure may be repeated any number of times with different names, until a stable state is reached.
We will start with uppercase names (you may wish to repeat each of these cycles, to ensure that, for whatever reason, you did not forget any occurrence):
for i in `grep -rl BANK .` do sed -i 's/BANK/CLUB/g' $i done
Then:
for i in `grep -rl Bank .` do sed -i 's/Bank/Club/g' $i done
And, finally:
for i in `grep -rl bank .` do sed -i 's/bank/club/g' $i done
That's all.
If you did everything right, a simple make inside each library's directory (in the current "mess" directory) should give you your new "club" libraries, albeit still doing the same actions of the original application (under different names).
There may be compilation problems for the po-club-textui library, but this is to be expected, since the strings library is completely different. The idea is to regard this as a particularly annoying bug and go from there in the direction of the project you want to implement. Step by step. Baby steps.
Start with some concept that already exists and shares some of the features you want to implement: for instance, a bank client may be similar to a club member...
Good luck.