View source for Quick-and-Dirty Guide to Transforming the Bank Application into your Very Own Project

{{TOCright}}
'''<font color="red">THIS PAGE IS OBSOLETE</font>'''

See [[Comando (padrão de desenho)/Banco, Conta, Titular (aplicação bancária)]].

= Introduction =

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 Goods =

The following are the components of the bank application (these are the 2010/2011 editions):
* [[Media:po-uilib-201308300030.tar.bz2|po-uilib-201308300030.tar.bz2]] - Base interaction package, a.k.a. '''po-uilib'''
* [[Media:po-bank-core-201308300030.tar.bz2|po-bank-core-201308300030.tar.bz2]] - Core functionality, a.k.a. '''bank-core'''
* [[Media:po-bank-support-201308300030.tar.bz2|po-bank-support-201308300030.tar.bz2]] - Support code (labels, messages, user interface exceptions), a.k.a. '''bank-support'''
* [[Media:po-bank-textui-201308300030.tar.bz2|po-bank-textui-201308300030.tar.bz2]] - Text-based user interface, a.k.a., '''bank-textui'''

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).

= Simply Compiling and Running the Application =

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).

== The Abstract User Interface Library: po-uilib ==

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 12.3):

* http://download.opensuse.org/repositories/home:/d4vid:/po13/openSUSE_12.3/

Other distributions may become supported (but remember: tests are run '''only''' on openSUSE 12.3). Check:

* http://download.opensuse.org/repositories/home:/d4vid:/po13/

== The Support (strings) Library: po-bank-support ==

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.

== The Core Library: po-bank-core ==

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.

== The User Interface Library: po-bank-textui ==

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.

== Running 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 ('''bank.textui.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 bank.textui.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 bank.textui.App BPO

= Rebuild the Bank Application as another Project =

<font color="red">'''DO NOT DO THIS FOR THE PROJECT -- THE CODE IS ALREADY IN THE CVS REPOSITORY'''</font>

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.

== Unpacking the Club Strings Library (provided) ==

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):

* http://download.opensuse.org/repositories/home:/d4vid:/po13/openSUSE_12.3/

Other distributions may become supported (but remember: tests are run '''only''' on openSUSE 12.3). Check:

* http://download.opensuse.org/repositories/home:/d4vid:/po13/

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).

== Unpacking the Core Library ==

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

<font color="brown">''Do not change the current directory from "mess"''.</font>

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.

[[category:PO]]
[[category:Ensino]]
[[en:Object-Oriented Programming]]