PHP

1 - PHP OVERVIEW

What is PHP?

The PHP: Hypertext Preprocessor (PHP) is known as a programming language that enables web developers creating dynamic content that communicates with the data source.

PHP is an open-source program, that means it is available for free on the Web. PHP can also be used across many platforms, such as Linux, many variations of the Unix system, Mac OS X, and Microsoft Windows.

PHP is a complete programming language and can be used for functions such as server-side scripting (using a web server to fulfill a user’s request by running a script directly on the web server like Apache, to generate dynamic HTML pages).

PHP is actually made to use for developing web-based software programs.

This PHP tutorial enables you to build your foundation with PHP.

Audience of this tutorial

This tutorial is made for those who’re not fully aware of PHP basics, however, they have knowledge of computer programming.

Requirements for PHP Tutorial

Before continuing with this guide, you need to have at least the basic knowledge of computer programming, Internet, DBMS, and MySQL database etc.

Lets Get Started

2 - PHP SYNTAX BASICS

Learn basics of PHP syntax

Escaping to PHP

The web pages usually contain a mix of code. The PHP parser needs a way to differentiate PHP code from the other elements. This mechanism is called as ‘escaping to PHP‘. There are four methods of applying this:

Canonical PHP tags

This the most commonly used method that uses:

The whole PHP code is placed in between:

opening tag

Short-open (SGML-style) tags

Short or short-open tags look like this:

This is the shortest tags but is not recommended way. If your web page is using XML, the same syntax is used for this as well. To use this method you have to do two things to let PHP recognize these tags.

When you are building PHP, choose the –enable-short-tags configuration option.

Open your php.ini file and set the short_open_tag ON. This option must be disabled to parse XML with PHP since the similar syntax is used for XML tags.

ASP-style tags

ASP-style tags are used by Active Server Pages to delineate code blocks. The ASP-style tags look like this:

<%...%>

You have to set the configuration options in php.ini file in order to use the ASP-style tags.

The HTML like script tags

HTML script tags look like this:

Commenting PHP Code

The Comments are the lines inside your code pages that parser does not execute. This is for the developer reading purpose where the purpose of the code/page etc is mentioned.

Two ways by which you may comment in PHP code files are as follows:

Single-line comments

Multi-line commenting

The Multi-line commenting is normally used to provide pseudocode algorithms and detailed information when required. This style of commenting is same as used in the C Language.

Example of multi-line commenting:

PHP is whitespace insensitive

Whitespace is the stuff you type that is typically invisible on the screen, including spaces, tabs, and carriage returns (end-of-line characters).

The whitespace is considered as the character. PHP is insensitive in case of whitespaces that means if you have spaces, tabs, and carriage returns (end-of-line characters). It will not affect PHP execution. For example, the following lines will give the same output:

PHP is case sensitive language

See the following example:

This will produce the following result:

Variable casesensitive is 67

Variable CaseSensitive is

PHP statements are terminated by semicolons

A statement in PHP is any expression which is followed by a semicolon (;).

Any sequence of correct PHP statements that is enclosed by the PHP tags is a valid PHP program. See example below:

$greetings = "Welcome to PHP!";

Braces make blocks

The curly braces {} are used to enclose multiple statements like in the following example.

Although statements cannot be combined like expressions, you can always put a sequence of statements anywhere a statement can go by enclosing them in a set of curly braces.

Here both statements are equivalent:

Details of if else statement are in the coming chapters.

Until now you should have a basic taste of PHP syntax. Next chapter will take you through the Variable Types in PHP.

3 - PHP VARIABLES IN PHP

What is Variable

Just like in any programming language, PHP Variables are the mean to store information in the middle of the PHP programs.

Important things to know about PHP variables

Variables in PHP are declared/denoted by using a leading $ sign. e.g. $variablename

The most recent assignment to a variable is the value of that variable.

The assignment operator used in variables is ‘=’ sign where a variable is on the left and expression to be at the right side.

e.g. $variablename = “variable value”;

In PHP, variables can be declared before assignment but it is not necessary.

Variables are not intrinsic types i.e. a variable does not know if it will be used to store a number or string.

Before assigning any value, the variables have default values.

When necessary PHP can automatically convert types from one to another.

Types of variables

There is a total of 8 data types that are used to construct variables in PHP.

PHP Integers

PHP int is the whole numbers without a decimal point. Example of PHP int is:

PHP Double type

The Double are numbers with decimal point e.g. 1.234 or 50.1.

PHP Boolean data type

The Boolean variables may be assigned only two possible values. Either true or false. The example of PHP Boolean variable is:

PHP NULL type

The PHP Null type is a special variable type that has only one value i.e. Null

PHP Strings

Strings are combination of characters e.g. ‘PHP supports string operations.’

The escape sequence in strings

You can use the following escape sequence within strings for respective results:

\n means adding a new line.
\r meant to be replaced by the carriage-return character.
\t in a string means to replace by the tab character.
\$ is replaced by the dollar sign ($).
\” means a single double-quote (“).
\\ means to add a single backslash (\).

To learn more about strings and its functions go to its chapter: String in PHP.

Arrays

Arrays in PHP are names and the indexed collection of values. Please see the dedicated chapter for declaring and using Arrays in PHP.

Objects

Object variables store instances of classes. This can package another kind of values and functions specific to use a class.

Resources

These are the special type that hold references to resources external to PHP like database connection.

This chapter explained only first 5 types that are simple in nature. Arrays and Objects are the compound in nature that can package up other arbitrary values of arbitrary types. The later types will be explained in their respective chapters in this PHP tutorial.

Naming conventions of variables in PHP

For choosing the name of your PHP variables, a few rules should be followed:

Variable should start with a letter or an underscore “_”.
The variable names can be combinations of a-z, A-Z, 0-9 or _ i.e. alpha-numeric characters, and underscores.
If your variable is more than one word then it should be separated with an underscore e.g. $first_second.

4 - PHP OPERATORS

Introduction to PHP operators

To perform ‘operations’ on variable or values, the programming languages provide operators. For example 10 + 5 = 15. Where 10 and 5 are called operands while ‘+’ and ‘=’ are operators.

PHP provides all type of operators that are required to perform operations and can be categorized into following:

Arithmetic Operators
Comparison Operators
Logical Operators
Assignment Operators
Ternary Operators also knows as conditional operators

PHP Assignment Operator

The “=” sign is an assignment operator in PHP. This is used to assign the value to variables.

Examples:

PHP Arithmetic operators

To perform mathematical operations, PHP provides following arithmetic operators.

Operator	Name	Example
+	Addition	$a = 10 + 10;
_	Subtract	$a = 20 – 10;
*	Multiply	$a = 5 * 5;
/	Divide	$a = 50/5;
%	Modulus	$a % $b

Using Assignment Operator with Arithmetic operators

Increment/Decrement Operators in PHP

PHP Comparison Operators

The comparison operators are used to compare two values, numbers or strings. It results in true or false. For example, if $y=10 and $z=20 then following will result as follows

Logical Operators in PHP

PHP String Operators

As we have used in our chapters, the “.” (period) and “.=” operators are used as string operators.

The .(period) is used for Concatenation purpose. See example below

Output

This is Concatenation example! Usage of Concatenation assignment (.=) example

Output

This is Concatenation example!

5 - PHP PRINT STATEMENT

The print statement of PHP

The Print statement or command in PHP is used, as the name shows, to display the output of a given variable or expression.

The PHP Print statement can display the output of any type of data.

The Print Syntax

Following is the syntax of print statement:

print <expression>;

Example 1: Example 2:

Single line print statement

print "This is single line print statement"

Multi-line PHP print statement

Following is an example of the multi-line single print statement

Be careful when printing quotes!

Follow these guidelines to use quotes as using the print statement to display strings. Follow these guidelines to use quotes as using the print statement to display strings.

Use a backslash (\) within the strings to escape your quotes. Before the quotation mark just place a backslash.

Inside your strings use single quotes (‘ ‘)

See examples below:

Print PHP Variables

Printing PHP variables is simple. It simply requires writing the print PHP statement followed by a variable name. See examples below:

Output is : Hello Mike. My name is: 4a Output is : 30

6 - PHP ECHO

The echo statement in PHP

The echo statement in PHP is used to display the output of a given expression.

You can use the echo statement to display any type of data in PHP. For example numbers, strings, variables or any other expression.

Following is the syntax to use the echo statement followed by examples.

PHP echo Syntax

Following is the general syntax of echo statement:

echo <expression|variable>;

Example of using echo:

This is how you can use echo statement to display a string or variable’s value.

You can see, echo keyword is followed by the string in double quotes. Similarly, you can use a variable name with a $ sign to display the variable value.

Another Example of displaying with echo:

The following piece of code shows how echo PHP statement is used in different ways, including displaying different strings.

Dealing with quotes in echo

In many cases, you will need to display quotes (“”) inside your paragraphs or strings. Be careful when you are doing this with PHP echo statement. Since, the echo uses quotes in the beginning and end of strings. In that case, you should use one of the methods below when your strings contain quotations.

Avoid using quotes inside the strings.
Use a backslash (\) within the strings to escape quotes. Before the quotation mark just place a backslash.
Inside your strings use single quotes (‘ ‘)

Check out the example below in order to get q better idea:

echo PHP Variables

Displaying variables in PHP by using the echo statement is quite simple. This is mentioned in the above section as well. See the following examples online to see how it works.

In the first example, three variables are used and assigned values. After that, echo statement is used to display the values of those variables.

Output is : Hello Mike. My name is: 4a

See another example with numbers

In this example, two variables with numbers are defined. The third variable is assigned the sum of other two variables. Finally, we used the PHP echo statement to display the third variable.

Output is : 30

7 - PHP IF / ELSE

The if statement in PHP

The PHP ‘If’ comes into action wherever options come. Where there are more than one options for anything for any matter we have to decide.

In programming, we use one of the methods to handle this is by using If and if-else PHP statements, also known as the decision making statements – to take decisions based on different situations.

Types of decision-making statements in PHP

There are three types of decision-making statements in PHP. Each of these types is explained below with an example.

PHP if else statement

The if PHP statement is used when there are only two options or outcomes for any situation. For example, choose head or tail. If the head comes then you win otherwise you loose. Each situation has its own course of action.

In situations where there are only two possibilities, you can place one block of code in the if statement when condition is true and (optionally) place the other block of code if the condition is false in PHP else block.

The if…else Syntax

The if example

"; } ?>

You can see, the if statement can be used in PHP without the else statement.

Execute more than one lines example

You can execute more than one lines in PHP if statement by using the curly braces as shown below:

The if else example

Following is a PHP if else example:

PHP elseif statement

Use the elseif statement where you have more than 2 situations to execute the code. You will initiate PHP if by using the if statement followed by a block of code to execute. After that, the other condition is enclosed in the elseif and so on.

Finally, you can place the "else" statement. When all conditions are false the else block of code will execute. See PHP elseif syntax and example below:

Syntax of elseif

Following is the syntax to use elseif PHP statement:

The elseif Example

Following is PHP elseif example:

PHP Switch Statement

Use this option when you have many options and have to execute one of those.

8 - PHP SWITCH CASE

Introduction to PHP Switch Case

The "Switch / case" is a type of decision-making statement in PHP. Use PHP Switch / case statement option when you have many options and have to execute one of those.

This is helpful where you have to use long blocks of if..elseif..else code. For example, if you have to execute a different block of code for different days of the Week or Month etc.

Syntax of switch case PHP

Following is the syntax to use switch case statement of PHP.

You can see, the switch statement contains an expression which is evaluated against each case. Each case, PHP statement, also contains a break statement which is explained below. The default section executes if none of the case is true (see details in the last section).

Example of using PHP switch case

The following example uses the names of Weekdays in switch case and executes a block of code that turns out to be true.

PHP break statement

You have to use the PHP break statement in order to quit parser from the switch case statement. If you do not use the break statement, the code will keep on executing for the next cases.

As you use the break statement in a case block that evaluates as true, it will execute the statements in that block and exit the switch PHP and execution will move to the next line of code out of switch statement.

See example below for what happens if you do not use a break statement in the above example.

The output will be: Its Tuesday today Its Wednesday today Its Thursday today Its Friday today Its Saturday today Its Sunday today

Switch in PHP with Default case

In the above example, there is no chance that among all of the cases, none of the case will be true. However, in many cases there will be situations where all conditions/cases are false.

In case of the If statement, we used the else statement. In Switch statement, we use the Default case. So the block of code inside the default case will be executed if all of the cases are false. See example below:

You can check by changing the variable name value from NY to IL, Al and then to some other to see the output. As you give some other value that does not exist in PHP switch cases then the default case block will be executed.

9 - PHP FOR LOOP

The for loop in PHP

Loops are the way to execute specified block of code again and again to a given number of times. There will be many scenarios in programming life when you need one or the other type of loop in order to achieve a task.

Types of loops in PHP

The for loop
while loop
do…while loop
foreach – loop

This chapter will discuss PHP For loop only. The for loop, also known as iteration statement is generally used when you know the number of iterations in loops.

Structure of for loop

Following is the general structure of PHP for loop:

for ( initialization; condition; increment the counter){

Code to be executed;

}

The first parameter in for loop PHP sets a counter initial value.
The second parameter tells until when code should be executed.
The Third parameter increments/decrements a counter.
Execute the code within the for loop enclosed in curly braces.

Example of for loop in PHP

In the following example, a variable i is initialized with a value of 0. The loop iterates through until the value of variable i reach 5. In each iteration, the variable will be incremented by 1.

In the curly braces, we used a print statement to display the current value of i. See the example by clicking the link below or copy/paste the code in your editor:

For loop – more real example

Following example mixes HTML with PHP for loop to generate HTML table as the output with Quantity and price headers.

10 - PHP WHILE LOOP

Introduction to While loop of PHP

The While loop is used to execute a block of code until the given condition is true. The condition check is similar to the one used in the PHP if statement to check if the condition is true or false.

In While PHP loop, after the code has been executed, the conditional statement will again be evaluated and the loop will continue until the given expression is found to be false.

The while loop Structure

Following is the general structure of PHP While loop:

while ( condition ){

//block of code here;

Increment;

}

Example of While loop

The following example shows using the PHP While loop. The variable i is initiated with the value 0 and then incremented after executing statements by 1. The loop will go on until the value of i reaches 5.

While loop example with HTML

Following example uses the HTML table and fills with data based at While loop.

The output of the above code will be a table filled with Quantity and price as PHP while loops through the variable i.

The PHP do while loop also works alike except the do while loop will execute the code at least once and then meet the condition. For more on do while and other loops visit the dedicated chapters by the links given below.

11 - PHP STRINGS

The Strings in PHP

Strings are the combination of characters. e.g. “Strings are supported in PHP”.

In this chapter, we will give you examples of creating, using and important functions associated with strings.

Creating PHP string

Following are examples of how you can create strings in PHP:

You may enclose strings in double quotes e.g. “”.
You can use single quotes to enclose strings as well.

e.g. $str1 = ‘This string is enclosed in single quotes';

The difference between single and double quote string in PHP is the double-quoted strings will replace variables inside the strings to their values. Also, the double quoted strings interpret certain character sequences.

See the following example: Following will be output

It will not print $var_name!

It will print name

In the above code, you can see the strings are created by using the single and double quotes. Two string variables are declared and assigned the values. After that, the print statement is used to display those string values. As mentioned, while using the double quotes in string, you can use variables inside it. The variables will be replaced by its values when you display by using the print or echo statements of PHP.

Note, there is no specific limits in lengths of strings. Strings that are enclosed in double quotes will see the following characters, also known as escape sequence, as described below:

\n means adding a new line.
\r meant to be replaced by the carriage-return character.
\t If used in a string, it will be replaced by the tab character.
\$ If you need to use a $ sign in a string then use it.
\” means a single double-quote (“).
\\ means to add a single backslash (\).

Now, as you have gone through how to create and display the strings, let us explore a few important functions provided by PHP. Click on any function below to go into detail of that function.

Important PHP String functions

String Length function

PHP strlen()

String replace function

PHP str_replace()

Array to String function

PHP Implode() – Array to string

String contains function

strpos()

PHP split string

The Explode()

12 - PHP ARRAY

What is an array

An array is a type of variable in PHP that can store multiple values.

PHP Array is a data structure that can hold one or more values in a single variable.
The Arrays are basically mapped where each key is mapped to a value.
The array index of PHP starts from 0.
You can create array elements in two different ways which are explained below.

Why using PHP Array

For the beginners who have no idea about arrays may ask why we use arrays? Let us take an example to understand why arrays are utilized to store the values.

Consider, we want to store 50 US States in our PHP program in string variables. One way is to define 50 string variables where each variable can store one State name. For 50 State names, fifty variables will be defined and each will be assigned a State name.

The other way is to use arrays where you simply make the $State variable an array. By using that array, you can store all 50 names in that single array. Is not that simple?

How to make that $State an array is shown below.

An Array PHP Example

In this example, we declared and assigned a simple string variable, $state and assigned it a value. After that, we displayed the value by print statement.

If you run the code it will simply display:

New York Now let us do it by using a PHP Array

Similarly, if you need to store 100 numbers then you have to define 100 simple variables. On the other hand, it is quite easier and simpler to create an array of 100 elements.

How to Create or define a new Array in PHP

These are the ways to define the arrays in PHP:

$arr_name = Array(1,2,3,4);

$arrname[0]=”array value”;

First of all, an array ($arrname) is defined by using the array name followed by Array keyword on the right side along with elements. The array is created with four elements.

In the second line, an array is defined by array name ($arrname) followed by element number in braces [] to assign a value. The array element is on the left side and the value at the right side.

We have used the first way in the above example. The second way of defining arrays is shown in the example below.

How to print an array of PHP

Printing an array as a whole or by elements is easy in PHP. We can use the echo or print statements to accomplish that. An array can be referred by element index value that starts from 0.

See example:

In the above example, you can see an array is created by using element numbers that starts from 0 i.e. $emp_array[0], $emp_array[1] and so on. To print the array element, we also used the element index in print and echo statements. You can also loop through array elements by using the foreach loop type quite easily. See section below.

An array example with foreach loop

Following example displays PHP array elements by using a foreach loop type of PHP. This is quite simple to use, where we simply created a numeric array of 5 elements.

After that, we used a foreach loop and displayed the array elements.

see example below: The output will be:

Value is 1
Value is 2
Value is 3
Value is 4
Value is 5

Types of arrays of PHP

Following are the array types supported in PHP. Click on any type below to go to its dedicated chapter:

Numeric Arrays
Associative array
Multidimensional array
array_push

13 - PHP DATE

PHP Date Introduction

The first thing to learn in PHP date is to understand about timestamps and how it is measured. Basically, the time stamp is the number of seconds from Jan 1, 1970, @ 00:00 GMT. This measurement is used by the date function of PHP.

As you create a timestamp in PHP you simply get a string of numbers that may look meaningless. It represents the number of seconds since the date you mentioned.

PHP gives you many options to format date and time as per the requirement like time zones, showing date in different formats etc. by using the date() function.

The date Syntax

Following is the general syntax of date in PHP: date(format, timestamp)

The format is the required parameter that specifies the timestamp format.
The timestamp is an optional parameter. Default is the current date and time.

Formatting Characters in date

Following is the list of characters that can be used as format parameters for formatting Day, Month, Year and Time.

Day formatting characters

d – its day of the month and can range from 01 to 31.
D – Day of Week in text format which is in 3 characters e.g. Mon, Tue etc.
z – returns the number of the day of the year – range is from 0-365.

Month parameters

m –Its the month range from 01 to 12.
n – returns a numeric number of month, without leading zeros (1 to 12).
M – returns short form of the month in three characters like Jan, Oct, Dec etc.
F – returns the full name of the month e.g. January, February, March etc.

Year format characters

y – Represents a year (in two digits).
Y – represents the year in four digits.
w – This returns the numeric value of the day (1 for Monday, 0 for Sunday).

PHP Time parameters

a – Lowercase Ante meridiem and Post meridiem, am or pm.
A – Uppercase Ante meridiem and Post meridiem, AM or PM.
B – Swatch Internet time, 000 through 999.
g – 12-hour format of an hour without leading zeros, 1 to 12.
G – 24-hour format of an hour without leading zeros, 0 to 23.
h – 12-hour format of an hour with leading zeros, 01 to 12.
H – 24-hour format of an hour with leading zeros, 00 to 23.
i – Minutes with leading zeros, 00 to 59.
s – Seconds, with leading zeros.

Now let us go through a few examples using PHP date() function.

PHP date format Example

The following example uses PHP date function, that will take the current time from the system and format it to m/d/y date format as output.

The output of above code is:

01/15/09

A date with another separator example

As such date formatting is quite flexible in PHP, in above example we use forward slash “/” to format dates. You can use other characters rather than using the forward slash.

The example below will display date by using ‘.’ to format the date using date PHP function. The format of date will be m.d.y.

Output: 01.15.09

Following example displays the current date in the Y-m-d format using date function. The year will be four digits like 2008 while the month with two digits like 01 for Jan and day number of Month.

Output: 2009- 01-15

Date formatting in day number, Month name and year format example

The Following example displays date by day number, Full Month name like January, March etc. and year in four digits like 2008 by using date PHP function!

Output: 15 January, 2009

Example of time and date

The following example returns the time and date by using the time function of PHP. The format will be m/d/y h: i: s.

An example of time zone

The following example will return the time zone by using ‘e’ formatting character with date function.

Example of time zone abbreviation

The following example will return the time zone abbreviation by using the ‘Z’.

14 - PHP FUNCTIONS

Introduction to function in PHP

Just like in other programming languages, PHP provides you the way to create and call functions.

A PHP function is a block of code that may take one or more input parameters, executes and may return a value. You can use functions repeatedly in PHP programs. A function’s code will only be executed once that function is called.

For example, built-in date and time functions in PHP like mktime(), MySQL function to establish a connection with database of MySQL (mysql_connect).

When you call these functions, you just know which parameters to pass but don’t know what the code is written to perform the ‘function’.

There are plenty of built-in functions, however, programmers can create their own custom functions. The functions make the life of programmer quite easier in that you don’t have to write the code again and again. You just need to understand what the purpose of a function, what are the required parameters and return values.

You even don’t need to go through the code, if a function is written by someone else, like PHP built-in functions or by other programmers.

You can write your own function in PHP, which is the purpose of this chapter for a single project or can use it in other projects as well.

Parts of PHP functions

There are two parts of a function in PHP:

Creating a function
Calling a function

Syntax of creating a function

You have to write the keyword function followed by the function_name(). All your code to be executed comes under curly braces.

Function of PHP example without a parameter

Following example shows how to create a PHP function. The is just a basic example that will execute statements and takes no input parameter.

Output This function will execute without needing a parameter

PHP Function example with parameters

Now we will go through a simple example of creating a PHP function, that takes two parameters as the input and displays the sum.

Output 30

In above example, when a function is called, the main program sends two variable values, $x and $y that are assigned to function’s parameters. The $x to $a and $y to $b parameter.

Function return example

Now we will go through an example of creating a function, that takes two parameters as input and the sum as the return value by function.

Function example with parameters and return value Output 30

In the above example, a function is created with two required parameters. While it returns a value by using the return command. When we call it from the PHP program we sent two variable values ($x,$y) and assigned to another variable of the same type to receive the returned value and finally displayed the output.

Function Optional Arguments Or Default Argument Value

It is possible to create a function with argument’s default values. In that case, while calling a function it becomes optional parameter. While function will use the default value.

See the example below Output 50

As we assigned the default values while defining our function to its parameters, those parameters became optional i.e. when you call it from PHP program, it is not mandatory to send parameters and in that case, the function uses default values without generating an error.

15 - PHP CLASS

What is a class?

Grouping similar types of tasks into classes comes under the object-oriented programming. Where a Class is a combination of variables/properties and functions/methods.

This chapter does not aim at explaining object oriented programming concepts thoroughly. The aim of this chapter is how to create and use PHP classes.

PHP Class

Class in PHP is a collection of variables and functions. Where functions work with these variables. A class, in general, can be taken as a template that is the basis of many instances in the form of objects.

For example, a model of a to be launched new car can be taken as a class. While once the model is approved and cars made on the basis of that approved template or ‘class’ can be taken as objects.

In this tutorial, we will use the same example of car class to explain how classes can be created and used and different features of classes available in PHP.

Syntax of defining class of PHP

Let me explain it line by line:

class MyPHPClass

class keyword is used to define the class name, MyPHPClass, followed by curly braces {}.
You can declare local variables in a class.
All the functions within the class must be created by using keyword function. e.g.

Function myPhpfunc ($par1, $par2)

The function keyword is followed by yourFunctionName and in small brackets () that contain any arguments.
Variables are declared by using var keyword followed by typical variable name with a $ sign. e.g.

var $intvar1;

A class example in PHP program

Following example shows how to create a class. We will use same car example as mentioned earlier.

setMan_price = $parameter;
 
    }
 
    function setcolor($parameter){
 
       $this->setcolor = $parameter;
 
    }
 
}
 
?>

Understanding Classes and Objects

As explained in the above example, when a manufacturer of cars plans a new model. Before launching and bringing hundred of thousands of cars, a model/prototype or template will be prepared and approved. Once approved, this can be the basis of manufacturing hundred of thousands of cars on the basis of that single model to bring in the market.

Now we can term that model or template as a PHP Class. Whereas all those cars made on that template basis are objects.

Just like that, a class is developed in Object Oriented Programming language like PHP (our current scope) that will be the basis of one or hundreds of PHP objects using that class.

Creating Objects of a Class

Once a class is created or defined, you can use it as many times as you need by using the PHP object variables as follows:

$obj = new className;

$Objcar = new carnewModel;

Class Inheritance

When a class is created by ‘inheriting’ function(s) of another class then this process is called Inheritance.

The class being inherited is called as the parent class while the calling class is called Child class. The child class will inherit variables and one or more functions from the parent class.

class Child_class_name extends Parent_class_name {

//Child class code: methods or properties

}

Extending our car example, let us say a car’s model (class) is approved and on that basis hundred of thousands of cars are in the market for sale. Now, the company has decided to give an added feature in a limited addition of that model. All of the features will remain the same in the limited addition plus one added feature.

So you don’t have to create a whole new model. Just ‘extend’ the existing one and add a new feature in it.

The carnewModel_limited_edition will inherit all methods and properties of carnewModel parent class.

PHP Abstract function in Class

An abstract class in OOP is the one that can only be inherited and cannot be instantiated.

Class constructor

While working with the classes, there will be scenarios when you will need to initialize something whenever an object is created for a class. PHP provides a magical or special function for that purpose called the class constructor.

The Constructor function will be called automatically when an object is created for that class. You may set variable initial values there or perform other operation that does not require a function call.

Syntax of creating Class Constructor

function __construct( $par1, $par2 ){

//Constructor Code goes here

}

So you have to use __construct to create a special function. You can send as many arguments as you need to the constructor function.

In continuity to our above example, let us set the initial variable values in below:

Output

The initial manufacturer price is: $15000

Initial color of car is: Black

As you can see, you only instantiated carnewModel class and the constructor function executing echo commands automatically.

Using Static in a class

A function or property declared as Static in PHP class can be accessed without creating the class objects. You simply have to refer the class name followed by scope resolution operator and static function name or property (variables).

Syntax of Using Static

public static $staic_property = ‘Static test';



public function static_func() {



return self::$staic_property;


}

Scope of Properties and Functions in classes

There are three ways how you can declare methods and functions in classes of PHP, that defines how properties and functions are accessible.

These are as follows:

1- Public

Properties and functions declared as the public are accessible both within the class and outside.

2- Private

Property or methods declared as private are only accessible within the class that defines it.

e.g.

private function pri_function()



{



//private function code;



}

3- Protected

Properties or methods declared as protected means, these are only accessible to the class that defines it or to child classes that extend it.

e.g.

protected function protected_func()



{



//Code goes here



}

16 - PHP SESSIONS

What is a session in PHP?

PHP Session variable is a way to store information in variables that can be used in multiple pages or across the website during that visit of a user. The session stores information on the server side unlike cookies, that store information at the user’s computer. Alternatively, you can say that session variables scope is global, unlike the normal variable which scope is specific to that page or a function.

As your website becomes more complicated, there will be a time when you need to store information to remember a particular visitor actions or data while navigating to other pages. A basic HTML site does not allow to store information that can be used across the website. The Sessions in PHP provide that mechanism.

For instance, in an eCommerce site storing shopping cart items, that has been added to the basket during that visit. Users keep on surfing other pages of the website, however, selected items are still shown.
Similarly, storing login information for a session.

The information stored in session PHP variables is temporary and finishes as the session ends or dies. For example, the user has closed the website.

How to start sessions

Now let us go through how session in PHP works. What we need to store user’s information and then using it to perform required actions.

This is how you can start a session:

So what it takes to start a session in PHP? You simply write the command, session_start();. This command should be placed on the top of the page even before HTML code. You must have to start the session in order to work with it.

So what actually happens when a session is started?

PHP creates a random unique identifier string of 32 hexadecimal numbers for that particular session. e.g. 9d5gpk75d2jj973hjkop2fc934s2578 (session id)
To store that unique identifier, a cookie is automatically sent to user’s computer. This cookie is called PHPSESSID.
In the specified temporary directory on the server side, a file is automatically created with the prefix sess_[unique identifier code].

Working with PHP session variables

Let us go through by an example how values are stored in PHP session variables.

Name this PHP file as test_session.php.

After starting the session, this is how session variables are assigned the values.

Like in above example, use $_SESSION[‘variable_name’]. $_SESSION[] is an associative array where it stores all session variables.

Using Session Variable

Now create a second file and write the following code to print/echo session variable values. Name this file as print_ test_session.php.

Output

My ID is: 1234



My Name is: Mike



My Location is: United States

So in the above example we created session PHP variable in one file and assigned values. In another PHP file, we simply displayed those session variables that carry the values.

Session timeout

By default, a session timeout period is set in the php.ini file (configuration file of PHP). A session will automatically be destroyed if a user’s browser is idle for a specified period.

You can change this time in php.ini or even specify session destroy time in your code file where you start a session.

Session time in PHP.ini file

Go to php.ini file and locate these variable to see and change if required:

//Sets to 60 mins

ini_set(‘session.gc_maxlifetime’,60*60);

ini_set(‘session.gc_probability’,1);

ini_set(‘session.gc_divisor’,1);

PHP Session Destroy

Though PHP automatically destroys a session after the timeout or a user has left the website. You may need to destroy specific variables, which purpose has been accomplished or destroy a session completely in an explicit way.

Syntax of destroying specific session variables

Following example shows the syntax of destroying specific PHP session variables by using PHP unset function.

Destroy session completely

In order to completely destroy a session use following:

17 - PHP COOKIES

Introduction to cookies in PHP

PHP Cookie is the way to save information at the client / visitor side. The information is generally related to the visitor e.g. login id, passwords, selected shopping cart items etc. Many big websites use cookies as well, usually those who allow to save passwords/ids e.g. gmail, facebook etc.

These days, many sites are using cookies as the way to store user’s information. However, the visitor has an option to disable or enable cookies at their browsers. That is why, the important information should not be stored at user’s computers that may affect the functionality of web application.

The session variables can also store the information, however, the difference between cookie and session in PHP is that cookies store information at the client side (visitors computer) whereas session stores information at the server side.

How to Set PHP cookie

Creating or setting PHP cookies is an easy task. See the syntax below

Syntax: setcookie(name, value, expiration) The setcookie has three parameters

name – Sets the name of cookie at user’s computer. You must remember the name of the cookie in order to retrieve in future. e.g. UserID.
value – The value to be saved. e.g. 1234.
expiration – duration after which cookie will be expired/destroyed. For example, a few email interfaces say “save id/pass for 7 days” and so on.

PHP set cookie examples

We will set or create two cookies in visitor’s computer as follows:

That’s it. The above code will set/create two cookies: Visitorname and Visitorage and will expire in three hours.

Depending on your browser – chrome, firefox, IE or other you can see yourself after executing the above code.

Get cookie in PHP

The $_COOKIE[‘cookie_name’] is used to access cookies in PHP. This is how we can access cookies in PHP for the created cookies in above section.

Example of accessing cookie Output Name stored in cookie is – Mike

The above example gets created cookie [visitorname] which value was set to “Mike”, in the previous example.

Delete cookie in PHP

You have to use the setcookie() again in order to delete a cookie. For that, you should specify name argument and use a past date.

Example of PHP delete cookie

Tips regarding cookies

You should set PHP cookies at the header i.e. even before using any HTML or other code.
You can remove a PHP cookie by using the name only, however, it may not work always. So better is to use the past date argument as well.

18 - PHP MySQL

A brief about MySQL

The MySQL is an open-source relational database management system, now owned by Oracle Inc. MySQL is particularly popular for web-based applications.

The MySQL is supported by most of the server-side scripting languages like PHP. Many big sites use MySQL as its database.

MySQL is multi-user and multi-threaded DBMS.

To learn more about MySQL, go to its tutorial.

"LAMP" platform, which is a popular platform, MySQL is one of the 4 components. Where LAMP stands for:

L = Linux
A = Apache
M = MySQL
P = PHP

MySQL is available and can be installed on important Operating systems like Linux, BSD Unix, Windows and Mac.

PHP and MySQL

While PHP can work with any database like Oracle, Microsoft SQL Server etc. the most widely used is PHP with MySQL.

PHP provides many built-in functions to work with MySQL database. At the bottom, you can see a list of important functions available to connect and query MySQL database for retrieving, inserting and deleting data. Detail of each function can be found in their respective chapters.

Before starting to work with MySQL database, we assume that you have downloaded and installed MySQL. The purpose of this tutorial is to explain MySQL with PHP functions. It is not about working inside MySQL database to perform admin related or other operations.
If you are interested in learning about that then go to MySQL tutorial.

For the examples of this PHP MySQL tutorial, we also recommend to create:

a database testdb

with user = testuser

password = testpassword

Important Functions of PHP for MySQL

Using mysql_connect to connect with MySQL database

Insert Data

Retrieving/Select data

Update Data

PHP mysql_connect function

PHP provides built-in function mysql_connect to establish a database connection with MySQL database.

For PHP MySQL connect, see the syntax below:

connection mysql_connect(server,user,passwd,new_link,client_flag);

We have assumed that you have created a database for MySQL connection example with:

database name = testdb
user = tesuser
password = testpassword

at your local system.

In that case:

DB host = “localhost”

MySQL connect Example

Following example shows PHP script to establish MySQL connection:

PHP MySQL database Connection

In the above example, we just established MySQL connection by using a PHP function. The connection is not established to any specific database yet.

After connecting to MySQL, it is time to connect to a working database of MySQL, testdb by using the PHP mysql_select_db function.

Syntax of mysql_select_db mysql_select_db(“database_name”)

PHP MySQL Database connect Example

Following example uses the mysql_select_db function to establish a connection to MySQL database.

" ; mysql_select_db("testdb") or die(mysql_error()); echo "Connected to Database"; ?> Output

MySQL Connected successfully

Connected to Database

Now as MySQL is connected along with a specific database, it is time to perform insert, update and delete operations at tables of that database. See chapter dedicated here: PHP Mysql insert, update, delete.

The mysql_query() function

After establishing a connection to MySQL and its specific database, it is time to work with database records. Mostly we need to Insert, Update, retrieve or select and Delete records from the database tables.

PHP provides built-in function mysql_query() to achieve these tasks along with others. This chapter will explain how to use mysql_query() function to do these operations.

Syntax of mysql_query()

mysql_query(‘sql statement’,connection)

Where:

SQL statement = There you will place either direct or a string variable containing an SQL statement.
Connection = You can also place connection object here if a connection is not already established with a database.

Examples of using mysql_query()

Before we go through the examples, we are assuming that:

You have knowledge of SQL insert, delete, update statements.
You have installed MySQL database.
You have created a DB name = testdb.
You have created a user = testuser.
You have assigned this password to above user = testpassword.
You have created a table = tblstaff.

PHP mysql_query to insert data

This example enters a record into the tblstaff in testdb database

This should be the output:

MySQL Connected successfully

Connected to Database

Entered data successfully

This is a basic example of how to use mysql_query to insert data into a table of MySQL database.

In real time applications, this will be selected by users/visitors of your website through a user interface in HTML or some other front end. In that case, you have to capture values from the front end like HTML form, store data into PHP variables (temporarily), make an SQL statement and use the above example approach.

PHP MySQL to Update data

This example updates/modify a record of tblstaff in testdb database.

Output:

MySQL Connected successfully



Connected to Database



Record updated successfully

mysql_query to Select data and displaying by mysql_fetch_array

This example selects or retrieves data from the tblstaff table in the testdb database. After fetching data from tblstaff, it also displays the records.

<?php
 
$dbhostname = 'localhost';
 
$dbusername = 'testuser';
 
$dbpassword = 'testpassword';
 
$conn = mysql_connect($dbhostname, $dbusername, $dbpassword);
 
if(! $conn )
 
{
 
  die('Could not connect: ' . mysql_error());
 
}
 
mysql_select_db("testdb") or die(mysql_error());
 
$emp_salary = 7000;
 
$emp_id = 3;
 
$sql_statemanet = "select * from tblstaff";
 
$rec_select = mysql_query( $sql_statemanet);
 
if(! $rec_select )
 
{
 
  die('Could not retrieve data: ' . mysql_error());
 
}
 
//Displaying fetched records to HTML table
 
echo "<table border='1'>";
 
echo "<tr> <th>Employee Name</th> <th>Employee Salary</th> </tr>";
 
// Using mysql_fetch_array() to get the next row until end of table rows
 
while($row = mysql_fetch_array( $rec_select )) {
 
                // Print out the contents of each row into a table
 
                echo "<tr><td>";
 
                echo $row['employee_name'];
 
                echo "</td><td>";
 
                echo $row['employee_sal'];
 
                echo "</td></tr>";
 
}
 
mysql_close($conn);
 
?>

Output:

This example will output HTML table in the browser showing all records fetched from the tblstaff table in testdb database.

The mysql_query() function

Syntax of mysql_query()

mysql_query(‘sql statement’,connection) Where:

SQL statement = There you will place either direct or a string variable containing an SQL statement.
Connection = You can also place connection object here if a connection is not already established with a database.

Examples of using mysql_query()

Before we go through the examples, we are assuming that:

You have knowledge of SQL insert, delete, update statements.
You have installed MySQL database.
You have created a DB name = testdb.
You have created a user = testuser.
You have assigned this password to above user = testpassword.
You have created a table = tblstaff.

To learn about SQL insert, delete and update statements go to SQL or MySQL tutorials.

PHP mysql_query to insert data

This example enters a record into the tblstaff in testdb database

This should be the output:

MySQL Connected successfully



Connected to Database



Entered data successfully

PHP MySQL to Update data

This example updates/modify a record of tblstaff in testdb database.

Output:

MySQL Connected successfully



Connected to Database



Record updated successfully

mysql_query to Select data and displaying by mysql_fetch_array

This example selects or retrieves data from the tblstaff table in the testdb database. After fetching data from tblstaff, it also displays the records.

Output:

This example will output HTML table in the browser showing all records fetched from the tblstaff table in testdb database.

50-game

Python

Back

Home

1 - PYTHON OVERVIEW

What is python?

If you don't understand this, don't worry. Just skip it and move on.

Python is an interpreted programming language. For those who don't know, a programming language is what you write down to tell a computer what to do. However, the computer doesn't read the language directly - there are hundreds of programming languages, and it couldn't understand them all. So, when someone writes a program, they will write it in their language of choice, and then compile it - that is, turn it in to lots of 0s and 1s, that the computer can easily and quickly understand. A windows program that you buy is already compiled for windows - if you opened the program file up, you'd just get a mass of weird characters and rectangles. Give it a go - find a small windows program, and open it up in notepad or wordpad. See what garbled mess you get.

But that windows program is compiled for windows - no other machine can run that program, unless it has windows. What Python is, is a language which is never actually compiled in full - instead, an interpreter turns each line of code into 0s and 1s that your computer can understand this. And it is done on the fly - it compiles the bits of the program you are using as you are using them. If you were to quit the program and come back another day, it would compile the bits you are using, as you are using them, again. Seems a waste of time? Maybe, but the fact is that when you come back another day, you might be using a Windows instead of a Mac. You might send the program to a friend, who uses another type of computer. Or you might post your program on the internet, where everyone using all different types of systems might download it. That is the wonder of an interpreted programming language - it is like a language that EVERYONE can understand.

So why will civIV use Python?

Remember that garbled mess that you got when opening a program in notepad? Not much use to anyone, apart from the computer. And there is no reliable (or legal) way of turning that program back in to a programming language that you or I could understand.

The same is with Civ3 AI - it is compiled into a garbled mess. Nobody can understand it, and most of all, nobody can change it. Only Firaxis can change the AI, and they can't share the logic behind it with anyone.

With cIV, they decided to change that - they would leave the AI uncompiled in the language of Python, and have it compiled on-the-fly by an interpreter. This is so that Joe modder can look at the AI and change it, yet when it is neede to be used, the python interpreter turns it into 0s and 1s for your computer to understand. And it isn't permanently compiled into a garbled mess - you are still left with python code, that you can read, understand, and MODIFY!!!!!

2 - PYTHON INSTALLING PYTHON

How to install python

First download Python-2.4.1.exe by following this link. If you are a dialup user, keep in mind that the file is around 10MB
Run the file you just downloaded, and follow the prompts.

OK! Hopefully now everything is good! Now, to test if that just worked, type this in your DOS window:

Code Example 1- Testing the instalation python -V

If you forgot a CAPITAL V, you will accidently load python in verbose mode. Give it a go, see what happens. Just press CTRL-D to quit, or type 'quit' for quit instructions.

conclusion

Good work! Lesson 1 over! Next lesson, we learn our way around Python Interactive Mode, and write simple one-line pieces of code. I'll also have a lesson plan drawn up by then, so you can see where you are going. If any of our more experienced members have suggestions for the lesson plan, tell me!

3 - PYTHON UNDERSTANDING PROGRAMS

Introduction

OK! We have python installed, now what? Well, we program! And it is that simple (at least for now). Python makes it easy to run single lines of code - one-liner programs. Lets give it a go.

Opening IDLE

Go to the start menu, find Python, and run the program labelled 'IDLE' (Stands for Integrated Development Environment.

Now you are in the IDLE environment. This is the place you will be spending most time in. Here you can open a new window to write a program, or you can simply mess around with single lines of code, which is what we are going to do. Type the following and press enter: (don't type >>> as it should already be there)

>>> print "Hello, World!"

What happened? You just created a program, that prints the words 'Hello, World'. The IDLE environment that you are in immediately compiles whatever you have typed in. This is useful for testing things, e.g. define a few variables, and then test to see if a certain line will work. That will come in a later lesson, though.

Math in Python

Now try typing the stuff in bold. You should get the output shown in blue. I've given explainations in brackets.

>>> 1 + 1 2 >>> 20+80 100 >>> 18294+449566 467860 (These are additions) >>> 6-5 1 (Subtraction) >>> 2*5 10 (Multiply, rabbits!) >>> 5**2 25 (Exponentials e.g. this one is 5 squared) >>> print "1 + 2 is an addition" 1 + 2 is an addition (the print statement, which writes something onscreen) >>> print "one kilobyte is 2^10 bytes, or", 2**10, "bytes" one kilobyte is 2^10 bytes, or 1024 bytes (you can print sums and variables in a sentence. The commas seperating each section are a way of seperating clearly different things that you are printing) >>> 21/3 7 >>> 23/3 7 >>> 23.0/3.0 7.6666... (division, 2nd time ignoring remainder/decimals, 3rd time including decimals) >>> 23%3 2 >>> 49%10 9 (the remainder from a division)

As you see, there is the code, then the result of that code. I then explain them in brackets. These are the basic commands of python, and what they do. Here is a table to clarify them (because tables look cool, and make you feel smarter ;) ):

Remember that thing called order of operation that they taught in maths? Well, it applies in python, too. Here it is, if you need reminding:

parentheses ()
exponents **
multiplication *, division \, and remainder %
addition + and subtraction -

Order of Operations

Here are some examples that you might want to try, if you're rusty on this:

n the first example, the computer calculates 2 * 3 first, then adds 1 to it. This is because multiplication has the higher priority (at 3) and addition is below that (at lowly 4).

In the second example, the computer calculates 1 + 2 first, then multiplies it by 3. This is because parentheses (brackets, like the ones that are surrounding this interluding text ;) ) have the higher priority (at 1) and addition comes in later than that.

Also remember that the math is calculated from left to right, UNLESS you put in parentheses. The innermost parentheses are calculated first. Watch these examples:

In the first example, 4 -40 is calculated,then - 3 is done.

In the second example, 40 - 3 is calculated, then it is subtracted from 4.

Comments, Please

The final thing you'll need to know to move on to multi-line programs is the comment. Type the following (and yes, the output is shown):

A comment is a piece of code that is not run. In python, you make something a comment by putting a hash in front of it. A hash comments everything after it in the line, and nothing before it. So you could type this:

Comments are important for adding necessary information for another programmer to read, but not the computer. For example, an explanation of a section of code, saying what it does, or what is wrong with it. You can also comment bits of code by putting a # in front of it - if you don't want it to compile, but cant delete it because you might need it later.

Conclusion

There you go! Lesson 2 Completed. That was even shorter than lesson 1! Next lesson, we make programs with many lines of code, and save them, so we can actually send them to people. That's right, you don't have to retype every program you run! What an amazing innovation!

4 - PYTHON VARIABLES

Introduction

Well, we can make one-liner programs. So What? You want to send programs to other people, so that they can use them, without knowing how to write them.

Editing in Notepad

Writing programs in python to a file is VERY easy. Python programs are simply text documents - you can open them up in notepad, and have a look at them, just like that. So, go and open notepad. Type the following:

Code Example 1 - mary.py

Keep this exactly the same, down to where the commas are placed. Save the file as 'mary.py' - and make sure notepad doesn't add .txt to the end of the filename - You will have to tell it to save as any file, to avoid this. Turn off 'Hide known file extensions' in Windows Explorer, if it makes it easier.

Using the IDLE Environment

Now, open up the Python IDLE program (should be in your start menu). Click 'File > Open' and find mary.py and open it. if you cant find mary.py, set the open dialogue to 'Files of type: All Files (*)'. A new window will open, showing the program you just wrote. To run your program, click 'Run>Run Module' (or just press F5). Your program will now run in the main Python screen (Titled *Python Shell*) and will look like this:

Code Example 2 - mary.py output

You can also use IDLE to create Python programs, like what you did in notepad. Simply click 'File > New'. We will be writing all of our programs now in the python IDLE program - the notepad thing is just a demonstration to tell you that a .py file is just a simple text file, which anyone can see.

There are a couple of things to notice here:

First of all, the comment wasn't shown. That is good, because remember - comments aren't compiled. (try compiling it after removing the # - it comes out messy)
Second, is that the 3rd and 4th line got joined. This is because there is a comma just outside the inverted commas that surround the text. In the 'print' command, this stops the program from starting a new line on the screen when showing text.
You can also run the program from your command line program (e.g. MSDOS) - Open the prompt up, type 'cd path\to\your\file' then type 'python mary.py'. Your program will now execute in the command line.

VARIABLES

Now lets start introducing variables. Variables store a value, that can be looked at or changed at a later time. Let's make a program that uses variables. Open up IDLE, click 'File>New Window' - a new window now appears, and it is easy to type in programs. Type the following (or just copy and paste - just read very carefully, and compare the code to the output that the program will make):

Code Example 3 - Variables

Strings

As you can see, variables store values, for use at a later time. You can change them at any time. You can put in more than numbers, though. Variables can hold things like text. A variable that holds text is called a string. Try this program:

Code Example 4 - Strings The output will be:

Good Morning
Good Morning to you too!

As you see, the variables above were holding text. Variable names can also be longer than one letter - here, we had word1, word2, and word3. As you can also see, strings can be added together to make longer words or sentences. However, it doesn't add spaces in between the words - hence me putting in the " " things (there is one space between those).

Conclusion

Well done! We now understand longer programs, and know the use of variables. Next lesson, we look at functions, what they are, and how to use them.

5 - PYTHON LOOP

Introduction

Our final lesson before we get into interacting with human input. Can't wait, can you?)

Just imagine you needed a program to do something 20 times. What would you do? You could copy and paste the code 20 times, and have a virtually unreadable program, not to mention slow and pointless. Or, you could tell the computer to repeat a bit of code between point A and point B, until the time comes that you need it to stop. Such a thing is called a loop.

The 'while' loop

The following are examples of a type of loop, called the 'while' loop:

Code Example 1 - The while loop

How does this program work? Lets go through it in English:

Code Example 2 - plain-language while loop Code Example 3 - while loop process

#JUST GLANCE OVER THIS QUICKLY
#(It looks fancy, but is really simple)
Is 'a' less than 10? YES (its 0)
Make 'a' one larger (now 1)
print on-screen what 'a' is (1)

Is 'a' less than 10? YES (its 1)
Make 'a' one larger (now 2)
print on-screen what 'a' is (2)

Is 'a' less than 10? YES (its 2)
Make 'a' one larger (now 3)
print on-screen what 'a' is (3)

Is 'a' less than 10? YES (its 3)
Make 'a' one larger (now 4)
print on-screen what 'a' is (4)

Is 'a' less than 10? YES (its 4)
Make 'a' one larger (now 5)
print on-screen what 'a' is (5)

Is 'a' less than 10? YES (its 5)
Make 'a' one larger (now 6)
print on-screen what 'a' is (6)

Is 'a' less than 10? YES (its 6)
Make 'a' one larger (now 7)
print on-screen what 'a' is (7)

Is 'a' less than 10? YES (are you still here?)
Make 'a' one larger (now 8)
print on-screen what 'a' is (8)

Is 'a' less than 10? YES (its 8)
Make 'a' one larger (now 9)
print on-screen what 'a' is (9)

Is 'a' less than 10? YES (its 9)
Make 'a' one larger (now 10)
print on-screen what 'a' is (10)

Is 'a' less than 10? NO (its 10, therefore isn't less than 10)
Don't do the loop
There's no code left to do, so the program ends

So in short, try to think of it that way when you write 'while' loops. This is how you write them, by the way (and a couple of examples:

Code Example 4 - while loop form, and example

Remember, to make a program, you open IDLE, click File > New Window, type your program in the new window, then press F5 to run.

Boolean Expressions (Boolean... what?!?)

What do you type in the area marked {conditions that the loop continues}? The answer is a boolean expression.

What? A forgotten concept for the non-math people here. Never mind, boolean expression just means a question that can be answered with a TRUE or FALSE response. For example, if you wanted to say your age is the same as the person next to you, you would type:

My age == the age of the person next to me

And the statement would be TRUE. If you were younger than the person opposite, you'd say:

My age < the age of the person opposite me

And the statement would be TRUE. If, however, you were to say the following, and the person
opposite of you was younger than you:

My age < the age of the person opposite me

The statement would be FALSE - the truth is that it is the other way around. This is how a loop thinks - if the expression is true, keep looping. If it is false, don't loop. With this in mind, lets have a look at the operators (symbols that represent an action) that are involved in boolean expressions:

Table 1 - Boolean operators

Dont get '=' and '==' mixed up - the '=' operator makes what is on the left equal to what is on the right. the '==' operator says whether the thing on the left is the same as what is on the right, and returns true or false.

Conditional Statements

OK! We've (hopefully) covered 'while' loops. Now let's look at something a little different - conditionals.

Conditionals are where a section of code is only run if certain conditions are met. This is similar to the 'while' loop you just wrote, which only runs when x doesn't equal 0. However, Conditionals are only run once. The most common conditional in any program language, is the 'if' statement. Here is how it works:

Code Example 5 - if statement and example

Example 2 there looks tricky. But all we have done is run an 'if' statement every time the 'while' loop runs. Remember that the % just means the remainder from a division - just checking that there is nothing left over if the number is divided by two - showing it is even. If it is even, it prints what 'n' is.

'else' and 'elif' - When it Ain't True

There are many ways you can use the 'if' statement, do deal with situations where your boolean expression ends up FALSE. They are 'else' and 'elif'.

'else' simply tells the computer what to do if the conditions of 'if' arent met. For example, read the following:

Code Example 6 - the else statement

'a' is not greater than five, therefore what is under 'else' is done.

'elif' is just a shortened way of saying 'else if'. When the 'if' statement fails to be true, 'elif' will do what is under it IF the conditions are met. For example:

Code Example 7 - The elif statement

The 'if' statement, along with 'else' and 'elif' follow this form:

Code Example 8 - the complete if syntax

One of the most important points to remember is that you MUST have a colon : at the end of every line with an 'if', 'elif', 'else' or 'while' in it. I forgot that, and as a result a stack of people got stumped at this lesson (sorry ;) ).

Indentation

One other point is that the code to be executed if the conditions are met, MUST BE INDENTED. That means that if you want to loop the next five lines with a 'while' loop, you must put a set number of spaces at the beginning of each of the next five lines. This is good programming practice in any language, but python requires that you do it. Here is an example of both of the above points:

Code Example 9 - Indentation

Notice the three levels of indents there:

Each line in the first level starts with no spaces. It is the main program, and will always execute.
Each line in the second level starts with four spaces. When there is an 'if' or loop on the first level, everything on the second level after that will be looped/'ifed', until a new line starts back on the first level again.
Each line in the third level starts with eight spaces. When there is an 'if' or loop on the second level, everything on the third level after that will be looped/'ifed', until a new line starts back on the second level again.
This goes on infinitely, until the person writing the program has an internal brain explosion, and cannot understand anything he/she has written.

There is another loop, called the 'for' loop, but we will cover that in a later lesson, after we have learnt about lists.

Conclusion

And that is lesson 4! In lesson 5, we get into user interaction, and writing programs that actually serve a purpose. Can't wait!

6 - PYTHON FUNCTIONS

Introduction

Last lesson I said that we would delve into purposefull programming. That involves user input, and user input requires a thing called functions.

What are functions? Well, in effect, functions are little self-contained programs that perform a specific task, which you can incorporate into your own, larger programs. After you have created a function, you can use it at any time, in any place. This saves you the time and effort of having to retell the computer what to do every time it does a common task, for example getting the user to type something in.

Using a function

Python has lots of pre-made functions, that you can use right now, simply by 'calling' them. 'Calling' a function involves you giving a function input, and it will return a value (like a variable would) as output. Don't understand? Here is the general form that calling a function takes:

Code Example 1 - How to call a function function_name(parameters)

See? Easy.

Function_name identifies which function it is you want to use (You'd figure...). For example, the function raw_input, which will be the first function that we will use.
Parameters are the values you pass to the function to tell it what is should do, and how to do it.. for example, if a function multiplied any given number by five, the stuff in parameters tells the function which number it should multiply by five. Put the number 70 into parameters, and the function will do 70 x 5.

Parameters and Returned Values - Communicating with Functions

Well, that's all well and good that the program can multiply a number by five, but what does it have to show for it? A warm fuzzy feeling? Your program needs to see the results of what happened, to see what 70 x 5 is, or to see if there is a problem somewhere (like you gave it a letter instead of a number). So how does a function show what is does?

Well, in effect, when a computer runs a function, it doesn't actually see the function name, but the result of what the function did. Variables do the exact same thing - the computer doesn't see the variable name, it sees the value that the variable holds. Lets call this program that multiplied any number by five, multiply(). You put the number you want multiplied in the brackets. So if you typed this:

Code Example 2 - Using a function a = multiply(70)

The computer would actually see this:

Code Example 3 - What the computer sees a = 350

note: don't bother typing in this code - multiply() isn't a real function, unless you create it.

The function ran itself, then returned a number to the main program, based on what parameters it was given.

Now let's try this with a real function, and see what it does. The function is called raw_input, and asks the user to type in something. It then turns it into a string of text. Try the code below:

Code Example 4 - Using raw_input

Say in the above program, you typed in 'hello' when it asked you to type something in. To the computer, this program would look like this:

Code Example 5 - What the computer sees

Remember, a variable is just a stored value. To the computer, the variable 'a' doesn't look like 'a' - it looks like the value that is stored inside it. Functions are similar - to the main program (that is, the program that is running the function), they look like the value of what they give in return of running.

A Calculator Program

Lets write another program, that will act as a calculator. This time it will do something more adventerous than what we have done before. There will be a menu, that will ask you whether you want to multiply two numbers together, add two numbers together, divide one number by another, or subtract one number from another. Only problem - the raw_input function returns what you type in as a string - we want the number 1, not the letter 1 (and yes, in python, there is a difference.).

Luckily, somebody wrote the function input, which returns what you typed in, to the main program - but this time, it puts it in as a number. If you type an integer (a whole number), what comes out of input is an integer. And if you put that integer into a variable, the variable will be an integer-type variable, which means you can add and subtract, etc.

Now, lets design this calculator properly. We want a menu that is returned to every time you finish adding, subtracting, etc. In other words, to loop (HINT!!!) while (BIG HINT!!!) you tell it the program should still run.

We want it to do an option in the menu if you type in that number. That involves you typing in a number (a.k.a input) and an if loop.

Lets write it out in understandable English first:

Code Example 6 - human-language example

Lets put this in something that python can understand:

Code Example 7 - Python verion of menu

#calculator program

#this variable tells the loop whether it should loop or not.
# 1 means loop. anything else means don't loop.

loop = 1

#this variable holds the user's choice in the menu:

choice = 0

while loop == 1:
    #print what options you have
    print "Welcome to calculator.py"

print "your options are:"
    print " "
    print "1) Addition"
    print "2) Subtraction"

print "3) Multiplication"

print "4) Division"
    print "5) Quit calculator.py"
    print " "

choice = input("Choose your option: ")
    if choice == 1:
        add1 = input("Add this: ")
        add2 = input("to this: ")
        print add1, "+", add2, "=", add1 + add2
    elif choice == 2:
        sub2 = input("Subtract this: ")
        sub1 = input("from this: ")
        print sub1, "-", sub2, "=", sub1 - sub2
    elif choice == 3:
        mul1 = input("Multiply this: ")
        mul2 = input("with this: ")
        print mul1, "*", mul2, "=", mul1 * mul2
    elif choice == 4:
        div1 = input("Divide this: ")
        div2 = input("by this: ")
        print div1, "/", div2, "=", div1 / div2
    elif choice == 5:
        loop = 0
	
print "Thankyou for using calculator.py!"

Wow! That is an impressive program! Paste it into python IDLE, save it as 'calculator.py' and run it. Play around with it - try all options, entering in integers (numbers without decimal points), and numbers with stuff after the decimal point (known in programming as a floating point). Try typing in text, and see how the program chucks a minor fit, and stops running (That can be dealt with, using error handling, which we can address later.)

Define Your Own Functions

Well, it is all well and good that you can use other people's functions, but what if you want to write your own functions, to save time, and maybe use them in other programs? This is where the 'def' operator comes in. (An operator is just something that tells python what to do, e.g. the '+' operator tells python to add things, the 'if' operator tells python to do something if conditions are
met.)
This is how the 'def' operator works:

Code Example 8 - The def operator

function_name is the name of the function. You write the code that is in the function below that line, and have it indented. (We will worry about parameter_1 and parameter_2 later, for now imagine there is nothing between the parentheses.

Functions run completely independent of the main program. Remember when I said that when the computer comes to a function, it doesn't see the function, but a value, that the function returns? Here's the quote:

Functions run completely independent of the main program. Remember when I said that when the computer comes to a function, it doesn't see the function, but a value, that the function returns? Here's the quote:

To the computer, the variable 'a' doesn't look like 'a' - it looks like the value that is stored inside it. Functions are similar - to the main program (that is, the program that is running the function), they look like the value of what they give in return of running.

A function is like a miniture program that some parameters are given to - it then runs itself, and then returns a value. Your main program sees only the returned value. If that function flew to the moon and back, and then at the end had:

Code Example 9 - return return "Hello"

then all your program would see is the string "hello", where the name of the function was. It would have no idea what else the program did.

Because it is a seperate program, a function doesn't see any of the variables that are in your main program, and your main program doesn't see any of the variables that are in a function. For example, here is a function that prints the words "hello" onscreen, and then returns the number '1234' to the main program:

Code Example 10 - using return

Think about the last line of code above. What did it do? Type in the program (you can skip the comments), and see what it does. The output looks like this:

Code Example 11 - the output

So what happened?

That accounts for everything that happened. remember, that the main program had NO IDEA that the words "hello" were printed onscreen. All it saw was '1234', and printed that onscreen.

Passing Parameters to functions

There is one more thing we will cover in this (monsterously huge) lesson - passing parameters to a function. Think back to how we defined functions:

Code Example 12 - Defining functions with parameters

Where parameter_1 and parameter_2 are (between the parentheses), you put the names of variables that you want to put the parameters into. Put as many as you need, just have them seperated by commas. When you run a function, the first value you put inside the parentheses would go into the variable where parameter_1 is. The second one (after the first comma) would go to the variable where parameter_2 is. This goes on for however many parameters there are in the function (from zero, to the sky) For example:

Code Example 13 - how parameters work

When you run the function above, you would type in something like this: funnyfunction("meat","eater","man"). The first value (that is, "meat") would be put into the variable called first_word. The second value inside the brackets (that is, "eater") would be put into the variable called second_word, and so on. This is how values are passed from the main program to functions - inside the parentheses, after the function name.

A final program

Think back to that calculator program. Did it look a bit messy to you? I think it did, so lets re-write it, with functions.

To design - First we will define all the functions we are going to use with the 'def' operator (still remember what an operator is ;) ). Then we will have the main program, with all that messy code replaced with nice, neat functions. This will make it so much easier to look at again in the future.

Code Example 14 - Calculator program

# calculator program

# NO CODE IS REALLY RUN HERE, IT IS ONLY TELLING US WHAT WE WILL DO LATER
# Here we will define our functions
# this prints the main menu, and prompts for a choice
def menu():
    #print what options you have
    print "Welcome to calculator.py"
    print "your options are:"
    print " "
    print "1) Addition"
    print "2) Subtraction"
    print "3) Multiplication"
    print "4) Division"
    print "5) Quit calculator.py"
    print " "
    return input ("Choose your option: ")
    
# this adds two numbers given
def add(a,b):
    print a, "+", b, "=", a + b
    
# this subtracts two numbers given
def sub(a,b):
    print b, "-", a, "=", b - a
    
# this multiplies two numbers given
def mul(a,b):
    print a, "*", b, "=", a * b
    
# this divides two numbers given
def div(a,b):
    print a, "/", b, "=", a / b
    
# NOW THE PROGRAM REALLY STARTS, AS CODE IS RUN
loop = 1
choice = 0
while loop == 1:
    choice = menu()
    if choice == 1:
        add(input("Add this: "),input("to this: "))
    elif choice == 2:
        sub(input("Subtract this: "),input("from this: "))
    elif choice == 3:
        mul(input("Multiply this: "),input("by this: "))
    elif choice == 4:
        div(input("Divide this: "),input("by this: "))
    elif choice == 5:
        loop = 0

print "Thankyou for using calculator.py!"

# NOW THE PROGRAM REALLY FINISHES

The initial program had 34 lines of code. The new one actually had 35 lines of code! It is a little longer, but if you look at it the right way, it is actually simpler.

You defined all your functions at the top. This really isn't part of your main program - they are just lots of little programs, that you will call upon later. You could even re-use these in another program if you needed them, and didn't want to tell the computer how to add and subtract again.

If you look at the main part of the program (between the line 'loop = 1' and 'print "Thankyou for..."'), it is only 15 lines of code. That means that if you wanted to write this program differently, you would only have to write 15 or so lines, as opposed to the 34 lines you would normally have to without functions.

7 - PYTHON TRUPLES, LISTS AND DICTIONARIES

Introduction

Your brain still hurting from the last lesson? Never worry, this one will require a little less thought. We're going back to something simple - variables - but a little more in depth.

Think about it - variables store one bit of information. They may regurgitate (just not on the carpet...) that information at any point, and their bit of information can be changed at any time. Variables are great at what they do - storing a piece of information that may change over time.

But what if you need to store a long list of information, which doesn't change over time? Say, for example, the names of the months of the year. Or maybe a long list of information, that does change over time? Say, for example, the names of all your cats. You might get new cats, some may die, some may become your dinner (we should trade recipies!). What about a phone book? For that you need to do a bit of referencing - you would have a list of names, and attached to each of those names, a phone number. How would you do that?

the Solution - Lists, Tuples, and Dictionaries

For these three problems, Python uses three different solutions - Tuples, lists, and dictionaries:

Lists are what they seem - a list of values. Each one of them is numbered, starting from zero - the first one is numbered zero, the second 1, the third 2, etc. You can remove values from the list, and add new values to the end. Example: Your many cats' names.
Tuples are just like lists, but you can't change their values. The values that you give it first up, are the values that you are stuck with for the rest of the program. Again, each value is numbered starting from zero, for easy reference. Example: the names of the months of the year.
Dictionaries are similar to what their name suggests - a dictionary. In a dictionary, you have an 'index' of words, and for each of them a definition. In python, the word is called a 'key', and the definition a 'value'. The values in a dictionary aren't numbered - tare similar to what their name suggests - a dictionary. In a dictionary, you have an 'index' of words, and for each of them a definition. In python, the word is called a 'key', and the definition a 'value'. The values in a dictionary aren't numbered - they aren't in any specific order, either - the key does the same thing. You can add, remove, and modify the values in dictionaries. Example: telephone book.

Tuples

Tuples are pretty easy to make. You give your tuple a name, then after that the list of values it will carry. For example, the months of the year:

Code Example 1 - creating a tuple

Note that the '\' thingy at the end of sthurlow.comthe first line carries over that line of code to the next line. It is usefull way of making big lines more readable.
Technically you don't have to put those parentheses there (the '(' and ')' thingies) but it stops python from getting things confused.
You may have spaces after the commas if you feel it necessary - it doesn't really matter.

Python then organises those values in a handy, numbered index - starting from zero, in the order that you entered them in. It would be organised like this:

Table 1 - tuple indicies

And that is tuples! Really easy...

Lists

Lists are extremely similar to tuples. Lists are modifiable (or 'mutable', as a programmer may say), so their values can be changed. Most of the time we use lists, not tuples, because we want to easily change the values of things if we need to.

Lists are defined very similarly to tuples. Say you have FIVE cats, called Tom, Snappy, Kitty, Jessie and Chester. To put them in a list, you would do this:

Code Example 2 - Creating a List

As you see, the code is exactly the same as a tuple, EXCEPT that all the values are put between square brackets, not parentheses. Again, you don't have to have spaces after the comma.

You recall values from lists exactly the same as you do with tuples. For example, to print the name of your 3rd cat you would do this:

Code Example 3 - Recalling items from a list print cats[2]

You can also recall a range of examples, like above, for example - cats[0:2] would recall your 1st and 2nd cats.

Where lists come into their own is how they can be modified. To add a value to a list, you use the 'append()' function. Let's say you got a new cat called Catherine. To add her to the list you'd do this:

Code Example 4 - Adding items to a list

That's a little weird, isn't it? I'll explain. That function is in a funny spot - after a period (the '.' kind of period, not otherwise), after the list name. You'll get to see those things more in a later lesson. For the meanwhile, this is the form of the function that adds a new value to a list:

Code Example 5 - Using the append function

Clears things up? Good!

Now to a sad situation - Snappy was shot by a neighbour, and eaten for their dinner (good on 'em!). You need to remove him (or her) from the list. Removing that sorry cat is an easy task, thankfully, so you have to wallow in sadness for as short a time as possible:

Code Example 6 - Deleting an item

You've just removed the 2nd cat in your list - poor old Snappy.

And with that morbid message, lets move on to...

Dictionaries

Ok, so there is more to life than the names of your cats. You need to call your sister, mother, son, the fruit man, and anyone else who needs to know that their favourite cat is dead. For that you need a telephone book. Now, the lists we've used above aren't really suitable for a telephone book. You need to know a number based on someone's name - not the other way around, like what we did with the cats. In the examples of months and cats, we gave the computer a number, and it gave us a name. This time we want to give the computer a name, and it give us a number. For this we need
Dictionaries.

So how do we make a dictionary? Put away your binding equipment, it isn't that advanced.

Remember, dictionaries have keys, and values. In a phone book, you have people's names, then their numbers. See a similarity?

When you initially create a dictionary, it is very much like making a tuple or list. Tuples have ( and ) things, lists have [ and ] things. Guess what! dictionaries have { and } things - curly braces. Here is an example below, showing a dictionary with four phone numbers in it

Code Example 7 - Creating a dictionary

the program would then print Lewis Lame's number onscreen. Notice how instead of identifying the value by a number, like in the cats and months examples, we identify the value, using another value - in this case the person's name.

Ok, you've created a new phone book. Now you want to add new numbers to the book. What do you do? A very simple line of code:

Code Example 8 - Adding entries to a dictionary

All that line is saying is that there is a person called Gingerbread Man in the phone book, and his number is 1234567. In other words - the key is 'Gingerbread Man', and the value is 1234567.

You delete entries in a dictionary just like in a list. Let's say Andrew Parson is your neighbour, and shot your cat. You never want to talk to him again, and therefore don't need his number. Just like in a list, you'd do this:

Code Example 9 - Removing entries from a dictionary

Again, very easy. the 'del' operator deletes any function, variable, or entry in a list or dictionary (An entry in a dictionary is just a variable with a number or text string as a name. This comes in handy later on.) remember that append function that we used with the list? Well, there are quite a few of those that can be used with dictionaries. Below, I will write you a program, and it will incorporate some of those functions in. It will have comments along the way explaining what it does. Type this program into Python IDLE (you can skip the comments). Experiment as much as you like with it. Type it where you see the lines beginning with >>>

Code Example 10 - Functions of dictionaries

#A few examples of a dictionary #First we define the dictionary #it will have nothing in it this time ages = {} #Add a couple of names to the dictionary ages['Sue'] = 23 ages['Peter'] = 19 ages['Andrew'] = 78 ages['Karren'] = 45 #Use the function has_key() - #This function takes this form: #function_name.has_key(key-name) #It returns TRUE #if the dictionary has key-name in it #but returns FALSE if it doesn't. #Remember - this is how 'if' statements work - #they run if something is true #and they don't when something is false. if ages.has_key('Sue'): print "Sue is in the dictionary. She is", \ ages['Sue'], "years old" else: print "Sue is not in the dictionary" #Use the function keys() - #This function returns a list #of all the names of the keys. #E.g. print "The following people are in the dictionary:" print ages.keys() #You could use this function to #put all the key names in a list: keys = ages.keys() #You can also get a list #of all the values in a dictionary. #You use the values() function: print "People are aged the following:", \ ages.values() #Put it in a list: values = ages.values() #You can sort lists, with the sort() function #It will sort all values in a list #alphabetically, numerically, etc... #You can't sort dictionaries - #they are in no particular order print keys keys.sort() print keys print values values.sort() print values #You can find the number of entries #with the len() function: print "The dictionary has", \ len(ages), "entries in it"

Conclusion

There are many other functions you can use to work with lists and dictionaries - too many to go through right now. We'll leave the lesson at this point - you have learnt enough for one lesson.

8 - PYTHON FOR LOOP

Introduction

Well, in the first lesson about loops, I said I would put off teaching you the for loop, until we had reached lists. Well, here it is!

The 'for' Loop

Basically, the for loop does something for every value in a list. The way it is set out is a little confusing, but otherwise is very basic. Here is an example of it in code

Code Example 1 - The for Loop

As you see, when the loop executes, it runs through all of the values in the list mentioned after 'in'. It then puts them into value, and executes through the loop, each time with value being worth something different. Let's see it a again, in a classic cheerleading call that we all know:

Code Example 2 - A for Loop Example

A couple of things you've just learnt:

As you see, strings (remember - strings are lines of text) are just lists with lots of characters.
The program went through each of the letters (or values) in word, and it printed them onscreen.

And that is all there is to the for loop. Making a Menu Function

Now to the business end of the lesson. Lets start writing programs. So far we have learnt variables, lists, loops, and functions. That is pretty much all we need for quite a bit of programming. So let's set ourselves a task.

Code Example 3 - A menu function

# THE MENU FUNCTION
# The program asks for a string with all the menu options in it,
# and a text string asking a question.
# make sure every menu entry is unique.

def menu(list, question):
    for entry in list:
        print 1 + list.index(entry),
        print ") " + entry

return input(question) - 1

# def menu(list, question): is telling the function to
# ask for two bits of information:
# A list of all the menu entries,
# and the question it will ask when all the options have been printed

# for entry in list: is pretty much saying;
#'for every entry in the list, do the following:'

# print list.index(entry) + 1 uses the .index() function to find
# where in the list the entry is in. print function then prints it
# it adds 1 to make the numbers more intelligable.

# print ") " + entry prints a bracket, and then the entry name

# after the for loop is finished, input(question) - 1 asks the question,
# and returns the value to the main program (minus 1, to turn it back to
# the number the computer will understand).

That wasn't very difficult, was it? the actual program only took up five lines - this is the wonder of how much we have learnt so far! All my comments take up sixteen lines - more than three times the program length. It is a good idea to comment your programs extensively. Remember that if you are going to be publishin gyour code open-source, there are going to be a lot of people checking out the code that you have written. We'll see the function we just wrote in our first example program.

Our First 'Game'

What will our first example program be? How about a (very) simple text adventure game? Sounds like fun! It will only encompass one room of a house, and will be extremely simple. There will be five things, and a door. In one of the five things, is a key to the door. You need to find the key, then open the door. I will give a plain-english version first, then do it in python:

Code Example 4 - Plain-english version of code

From this, we can write a real program. Ready? Here it is (skip typing the comments):

Code Example 5 - Text Adventure Game

#TEXT ADVENTURE GAME

#the menu function:
def menu(list, question):
    for entry in list:
        print 1 + list.index(entry),
        print ") " + entry

return input(question) - 1

#Give the computer some basic information about the room:
items = ["pot plant","painting","vase","lampshade","shoe","door"]

#The key is in the vase (or entry number 2 in the list above):
keylocation = 2

#You haven't found the key:
keyfound = 0

loop = 1

#Give some introductary text:
print "Last night you went to sleep in the comfort of your own home."

print "Now, you find yourself locked in a room. You don't know how"
print "you got there, or what time it is. In the room you can see"
print len(items), "things:"
for x in items:
    print x
print ""
print "The door is locked. Could there be a key somewhere?"
#Get your menu working, and the program running until you find the key:
while loop == 1:
    choice = menu(items,"What do you want to inspect? ")
    if choice == 0:
        if choice == keylocation:
            print "You found a small key in the pot plant."

print ""
            keyfound = 1
        else:
            print "You found nothing in the pot plant."
            print ""
    elif choice == 1:
        if choice == keylocation:
            print "You found a small key behind the painting."
            print ""

keyfound = 1
        else:
            print "You found nothing behind the painting."
            print ""
    elif choice == 2:
        if choice == keylocation:
            print "You found a small key in the vase."
            print ""
            keyfound = 1
        else:
            print "You found nothing in the vase."

print ""
    elif choice == 3:
        if choice == keylocation:
            print "You found a small key in the lampshade."
            print ""
            keyfound = 1
        else:
            print "You found nothing in the lampshade."
            print ""

elif choice == 4:
        if choice == keylocation:
            print "You found a small key in the shoe."
            print ""
            keyfound = 1
        else:
            print "You found nothing in the shoe."
            print ""
    elif choice == 5:
        if keyfound == 1:
            loop = 0
            print "You put in the key, turn it, and hear a click"

print ""
        else:
            print "The door is locked, you need to find a key."
            print ""

# Remember that a backslash continues
# the code on the next line

print "Light floods into the room as \
you open the door to your freedom."

Well, a very simple, but fun, game. Don't get daunted by the amount of code there, 53 of the lines are just the 'if' statements, which is the easiest thing to read there (Once you comprehend all the indentation. Soon you'll make your own game, and you can make it as simple (or as complex) as you like. I'll post quite a few, later.

Making the game better

The fist question you should ask is "does this program work?". The answer here is yes. Then you should ask "does this program work well?" - not quite. The menu() function is great - it reduces a lot of typing. The 'while' loop that we have, however, is a little messy - four levels of indents, for a simple program. We can do better!

Now, this will become much MUCH more straightforward when we introduce classes. But that will have to wait. Until then, let's make a function that reduces our mess. It we will pass two things to it - the menu choice we made, and the location of the key. It will return one thing - whether or not the key has been found. Lets see it:

Code Example 6 - Creating an inspect function

Now the main program can be a little simpler. Let's take it from the while loop, and change things around:

Code Example 7 - The new game

Now the program becomes massively shorter - from a cumbersome 83 lines, to a very shapely 50 lines! Of course, you lose quite a bit of versatility - all the items in the room do the same thing. You automatically open the door when you find the key. The game becomes a little less interesting. It also becomes a little harder to change.

conclusion

Now I said you would write some programs now. Here is your chance! Your task, if you chose to accept it, is to post a better text adventure game. You can use any of the code I have given you here. Remember to check back on previous lessons we have done - they are priceless tools. Do a search for some simple text adventure games - if you find some nice, fun text adventure games, have a look at them.

9 - PYTHON CLASSES

Introduction

One thing that you will get to know about programming, is that programmers like to be lazy. If something has been done before, why should you do it again?

That is what functions cover in python. You've already had your code do something special. Now you want to do it again. You put that special code into a function, and re-use it for all it is worth. You can refer to a function anywhere in your code, and the computer will always know what you are talking about. Handy, eh?

Of course, functions have their limitations. Functions don't store any information like variables do - every time a function is run, it starts afresh. However, certain functions and variables are related to each other very closely, and need to interact with each other a lot. For example, imagine you have a golf club. It has information about it (i.e. variables) like the length of the shaft, the material of the grip, and the material of the head. It also has functions associated with it, like the function of swinging your golf club, or the function of breaking it in pure frustration. For those functions, you need to know the variables of the shaft length, head material, etc.

That can easily be worked around with normal functions. Parameters affect the effect of a function. But what if a function needs to affect variables? What happens if each time you use your golf club, the shaft gets weaker, the grip on the handle wears away a little, you get that little more frustrated, and a new scratch is formed on the head of the club? A function cannot do that. A function only makes one output, not four or five, or five hundred. What is needed is a way to group functions and variables that are closely related into one place so that they can interact with each other.

Chances are that you also have more than one golf club. Without classes, you need to write a whole heap of code for each different golf club. This is a pain, seeing that all clubs share common features, it is just that some have changed properties - like what the shaft is made of, and it's weight. The ideal situation would be to have a design of your basic golf club. Each time you create a new club, simply specify its attributes - the length of its shaft, its weight, etc.

Or what if you want a golf club, which has added extra features? Maybe you decide to attach a clock to your golf club (why, I don't know - it was your idea). Does this mean that we have to create this golf club from scratch? We would have to write code first for our basic golf club, plus all of that again, and the code for the clock, for our new design. Wouldn't it be better if we were to just take our existing golf club, and then tack the code for the clock to it?

These problems that a thing called object-oriented-programming solves. It puts functions and variables together in a way that they can see each other and work together, be replicated, and altered as needed, and not when unneeded. And we use a thing called a 'class' to do this.

Creating a Class

What is a class? Think of a class as a blueprint. It isn't something in itself, it simply describes how to make something. You can create lots of objects from that blueprint - known technically as an instance.

So how do you make these so-called 'classes'? very easily, with the class operator:

Code Example 1 - defining a class

Makes little sense? Thats ok, here is an example, that creates the definition of a Shape:

Code Example 2 - Example of a Class

What you have created is a description of a shape (That is, the variables) and what operations you can do with the shape (That is, the fuctions). This is very important - you have not made an actual shape, simply the description of what a shape is. The shape has a width (x), a height (y), and an area and perimeter (area(self) and perimeter(self)). No code is run when you define a class - you are simply making functions and variables.

The function called __init__ is run when we create an instance of Shape - that is, when we create an actual shape, as opposed to the 'blueprint' we have here, __init__ is run. You will understand how this works later.

self is how we refer to things in the class from within itself. self is the first parameter in any function defined inside a class. Any function or variable created on the first level of indentation (that is, lines of code that start one TAB to the right of where we put class Shape is automatically put into self. To access these functions and variables elsewhere inside the class, their name must be preceeded with self and a full-stop (e.g. self.variable_name).

Using a class

Its all well and good that we can make a class, but how do we use one? Here is an example, of what we call creating an instance of a class. Assume that the code example 2 has already been run:

Code Example 3 - Creating a class

What has been done? It takes a little explaining...

The __init__ function really comes into play at this time. We create an instance of a class by first giving its name (in this case, Shape) and then, in brackets, the values to pass to the __init__ function. The init function runs (using the parameters you gave it in brackets) and then spits out an instance of that class, which in this case is assigned to the name rectangle.

Think of our class instance, rectangle, as a self-contained collection of variables and functions. In the same way that we used self to access functions and variables of the class instance from within itself, we use the name that we assigned to it now (rectangle) to access functions and variables of the class instance from outside of itself. Following on from the code we ran above, we would do this:

Code Example 4 - accessing attributes from outside an instance

As you see, where self would be used from within the class instance, its assigned name is used when outside the class. We do this to view and change the variables inside the class, and to access the functions that are there.

We aren't limited to a single instance of a class - we could have as many instances as we like. I could do this:

Code Example 5 - More than one instance

and both longrectangle and fatrectangle have their own functions and variables contained inside them - they are totally independent of each other. There is no limit to the number of instances I could create.

Lingo

Object-oriented-programming has a set of lingo that is associated with it. Its about time that we have this all cleared up:

When we first describe a class, we are defining it (like with functions)
The ability to group similar functions and variables together is called encapsulation
The word 'class' can be used when describing the code where the class is defined (like how a function is defined), and it can also refer to an instance of that class - this can get confusing, so make sure you know in which form we are talking about classes
A variable inside a class is known as an Attribute
A function inside a class is known as a method
A class is in the same category of things as variables, lists, dictionaries, etc. That is, they are objects
A class is known as a 'data structure' - it holds data, and the methods to process that data.

Inheritance

Lets have a look back at the introduction. We know how classes group together variables and functions, known as attributes and methods, so that both the data and the code to process it is in the same spot. We can create any number of instances of that class, so that we don't have to write new code for every new object we create. But what about adding extra features to our golf club design? This is where inheritance comes into play.

Python makes inheritance really easily. We define a new class, based on another, 'parent' class. Our new class brings everything over from the parent, and we can also add other things to it. If any new attributes or methods have the same name as an attribute or method in our parent class, it is used instead of the parent one. Remember the Shape class?

Code Example 6 - the Shape class

If we wanted to define a new class, lets say a square, based on our previous Shape class, we would do this:

Code Example 7 - Using inheritance

It is just like normally defining a class, but this time we put in brackets after the name, the parent class that we inherited from. As you see, we described a square really quickly because of this. That's because we inherited everything from the shape class, and changed only what needed to be changed. In this case we redefined the __init__ function of Shape so that the X and Y values are the same.

Let's take from what we have learnt, and create another new class, this time inherited from Square. It will be two squares, one immediately left of the other:

Code Example 8 - DoubleSquare class

This time, we also had to redefine the perimeter function, as there is a line going down the middle of the shape. Try creating an instance of this class. As a helpful hint, the idle command line starts where your code ends - so typing a line of code is like adding that line to the end of the program you have written.

Pointers and Dictionaries of Classes

Thinking back, when you say that one variable equals another, e.g. variable2 = variable1, the variable on the left-hand side of the equal-sign takes on the value of the variable on the right. With class instances, this happens a little differently - the name on the left becomes the class instance on the right. So in instance2 = instance1, instance2 is 'pointing' to instance1 - there are two names given to the one class instance, and you can access the class instance via either name.

In other languages, you do things like this using pointers, however in python this all happens behind the scenes.

The final thing that we will cover is dictionaries of classes. Keeping in mind what we have just learnt about pointers, we can assign an instance of a class to an entry in a list or dictionary. This allows for virtually any amount of class instances to exist when our program is run. Lets have a look at the example below, and see how it describes what I am talking about:

Code Example 9 - Dictionaries of Classes

As you see, we simply replaced our boring old name on the left-hand side with an exciting, new, dynamic, dictionary entry. Pretty cool, eh?

Conclusion

And that is the lesson on classes! You won't believe how long it took me to write this in a clear-cut manner, and I am still not completely satisfied! I have already gone through and rewritten half of this lesson once, and if you're still confused, I'll probably go through it again. I've probably confused some of you with my own confusion on this topic, but remember - it is not something's name that is important, but what it does (this doesn't work in a social setting, believe me... ;)).

10 - PYTHON MODULES

Introduction

Last lesson we covered the killer topic of Classes. As you can remember, classes are neat combinations of variables and functions in a nice, neat package. Programming lingo calls this feature encapsulation, but reguardless of what it is called, it's a really cool feature for keeping things together so the code can be used in many instances in lots of places. Of course, you've got to ask, "how do I get my classes to many places, in many programs?". The answer is to put them into a module, to be imported into other programs.

Module? What's a Module?

A module is a python file that (generally) has only defenitions of variables, functions, and classes. For example, a module might look like this:

Code Example 1 - moduletest.py

As you see, a module looks pretty much like your normal python program.

So what do we do with a module? We import bits of it (or all of it) into other programs.

To import all the variables, functions and classes from moduletest.py into another program you are writing, we use the import operator. For example, to import moduletest.py into your main program, you would have this:

Code Example 2 - mainprogram.py

This assumes that the module is in the same directory as mainprogram.py, or is a default module that comes with python. You leave out the '.py' at the end of the file - it is ignored. You normally put all import statements at the beginning of the python file, but technically they can be anywhere. In order to use the items in the module in your main program, you use the following:

Code Example 3 - mainprogram.py continued

As you see, the modules that you import act very much like the classes we looked at last lesson - anything inside them must be preceeded with modulename. for it to work.

More module thingummyjigs (in lack of a better title)

Wish you could get rid of the modulename. part that you have to put before every item you use from a module? No? Never? Well, I'll teach it you anyway.

One way to avoid this hassle is to import only the wanted objects from the module. To do this, you use the from operator. You use it in the form of from modulename import itemname. Here is an example:

Code Example 4 - importing individual objects

What is the point of this? Well, maybe you could use it to make your code a little more readable. If we get into heaps of modules inside modules, it could also remove that extra layer of crypticness.

If you wanted to, you could import everything from a module is this way by using from modulename import *. Of course, this can be troublesome if there are objects in your program with the same name as some items in the module. With large modules, this can easily happen, and can cause many a headache. A better way to do this would be to import a module in the normal way (without the from operator) and then assign items to a local name:

Code Example 5 - mainprogram.py continued

This way, you can remove some crypticness, AND have all of the items from a certain module.

Conclusion

That's it! A very simple lesson, but now you can organise your programs very neatly. In fact, now it is increadibly easy to make progams that can grow in complexity without ending up with one cryptic file that is full of bugs.

Modules are great for importing code. Next lesson, we learn about file input and output, and the saving of information inside classes, to be retrieved later. Will be great! But until then...

11 - PYTHON FILE I/O

Introduction

Last lesson we learnt how to load external code into our program. Without any introduction (like what I usually have), let's delve into file input and output with normal text files, and later the saving and restoring of instances of classes. (Wow, our lingo power has improved greatly!)

Opening a file

To open a text file you use, well, the open() function. Seems sensible. You pass certain parameters to open() to tell it in which way the file should be opened - 'r' for read only, 'w' for writing only (if there is an old file, it will be written over), 'a' for appending (adding things on to the end of the file) and 'r+' for both reading and writing. But less talk, lets open a file for reading (you can do this in your python idle mode). Open a normal text file. We will then print out what we read inside the file:

Code Example 1 - Opening a file That was interesting. You'll notice a lot of '\n' symbols. These represent newlines (where you pressed enter to start a new line). The text is completely unformatted, but if you were to pass the output of openfile.read() to print (by typing print openfile.read()) it would be nicely formatted.

Seek and You Shall Find

Did you try typing in print openfile.read()? Did it fail? It likely did, and reason is because the 'cursor' has changed it's place. Cursor? What cursor? Well, a cursor that you really cannot see, but still a cursor. This invisible cursor tells the read function (and many other I/O functions) where to start from. To set where the cursor is, you use the seek() function. It is used in the form seek(offset, whence).

whence is optional, and determines where to seek from. If whence is 0, the bytes/letters are counted from the beginning. If it is 1, the bytes are counted from the current cursor position. If it is 2, then the bytes are counted from the end of the file. If nothing is put there, 0 is assumed.

offset decribes how far from whence that the cursor moves. for example:

openfile.seek(45,0) would move the cursor to 45 bytes/letters after the beginning of the file.
openfile.seek(10,1) would move the cursor to 10 bytes/letters after the current cursor position.
openfile.seek(-77,2) would move the cursor to 77 bytes/letters before the end of the file (notice the - before the 77)

Try it out now. Use openfile.seek() to go to any spot in the file and then try typing print openfile.read(). It will print from the spot you seeked to. But realise that openfile.read() moves the cursor to the end of the file - you will have to seek again.

Other I/O Functions

There are many other functions that help you with dealing with files. They have many uses that empower you to do more, and make the things you can do easier. Let's have a look at tell(), readline(), readlines(), write() and close().

tell() returns where the cursor is in the file. It has no parameters, just type it in (like what the example below will show). This is infinitely useful, for knowing what you are refering to, where it is, and simple control of the cursor. To use it, type fileobjectname.tell() - where fileobjectname is the name of the file object you created when you opened the file (in openfile = open('pathtofile', 'r') the file object name is openfile).

readline() reads from where the cursor is till the end of the line. Remember that the end of the line isn't the edge of your screen - the line ends when you press enter to create a new line. This is useful for things like reading a log of events, or going through something progressively to process it. There are no parameters you have to pass to readline(), though you can optionally tell it the maximum number of bytes/letters to read by putting a number in the brackets. Use it with fileobjectname.readline().

readlines() is much like readline(), however readlines() reads all the lines from the cursor onwards, and returns a list, with each list element holding a line of code. Use it with fileobjectname.readlines(). For example, if you had the text file:

Code Example 2 - example text file

then the returned list from readlines() would be:

Table 1 - resulting list from readlines

The write() function, writes to the file. How did you guess??? It writes from where the cursor is, and overwrites text in front of it - like in MS Word, where you press 'insert' and it writes over the top of old text. To utilise this most purposeful function, put a string between the brackets to write e.g. fileobjectname.write('this is a string').

close, you may figure, closes the file so that you can no longer read or write to it until you reopen in again. Simple enough. To use, you would write fileobjectname.close(). Simple!

In Python idle mode, open up a test file (or create a new one...) and play around with these functions. You can do some simple (and very inconvenient) text editing.

Mmm, Pickles

Pickles, in Python, are to be eaten. Their flavour is just to good to let programmers leave them in the fridge.

Ok, just joking there. Pickles, in Python, are objects saved to a file. An object in this case could be a variables, instance of a class, or a list, dictionary, or tuple. Other things can also be pickled, but with limits. The object can then be restored, or unpickled, later on. In other words, you are 'saving' your objects.

So how do we pickle? With the dump() function, which is inside the pickle module - so at the beginning of your program you will have to write import pickle. Simple enough? Then open an empty file, and use pickle.dump() to drop the object into that file. Let's try that:

Code Example 3 - pickletest.py

The code to do this is laid out like pickle.load(object_to_pickle, file_object) where:

object_to_pickle is the object you want to pickle (i.e. save it to file)
file_object is the file object you want to write to (in this case, the file object is 'file')

After you close the file, open it in notepad and look at what you see. Along with some other gibblygook, you will see bits of the list we created.

Now to re-open, or unpickle, your file. to use this, we would use pickle.load():

Code Example 4 - unpickletest.py

Conclusion

Which ends this lesson.

Thanks to all,

50-game

Ruby

Back

Home

1 - RUBY OVERVIEW

This is a Ruby tutorial for one not knowing Ruby. Therefore, we use many constructs and styles that, while familiar to programmers and intuitive to beginners, are not optimal for Ruby. A companion document, Ruby the Right Way, discusses how to use Ruby to full advantage and have your code compatible with the vast body of Ruby code out there.

Ruby can be used as a fully object oriented language, in which case you'd create classes and objects to accomplish everything. However, it can be used quite nicely with only the objects and classes that ship with Ruby, in which case it can be used as a procedural language, except that functions are typically methods of the program's variables.

If that doesn't make any sense to you, don't worry, it's just a way of saying that Ruby can be very easy to learn and use.

Even if you want to become a Ruby expert, you need to learn the basic functionality before you can become a Ruby OOP ninja. This tutorial gives you those basics.

2 - RUBY HELLO WORLD

This is the simplest possible Ruby program, hello.rb. As you'd expect, it prints "Hello World" on the screen. Be sure to set it executable.

Although this program works as expected, it goes against the philosophy of Ruby because it's not object oriented. But as a proof of concept that Ruby's working on your computer, it's just fine.

Besides print, there's also a puts keyword. The difference is that puts automatically inserts a newline at the end of the string being printed, whereas print does not. In other words, puts is more convenient, but print is necessary if separate statements print to the same line. Througout this tutorial we'll use both print and puts.

3 - RUBY LOOPS

Let's count to 10...

The elipses (...) indicate the range through which to loop. The for is terminated by an end. You don't need braces for a loop. Whew!

The following is the output:

Notice that it stops on 9. The number following the elipses causes termination at the top of the loop. The 1...10 means 1 TO BUT NOT INCLUDING 10, it does NOT mean 1 through 10. Please remember this when using Ruby loops.

NOTE:

There are actually two versions of the elipses operator, the three period version as shown previously, and the two period version. The two period version is inclusive. In other words, 1...3 means 1 up to but not including 3, while 1..3 means one through 3.

By using the appropriate version of the elipses operator you can save having to code convoluted end conditions.

Now let's iterate through an array.

We defined an array of presidents using a Perl like syntax (except we used brackets instead of parens), and we iterated from 0 (Ruby is 0 based, like most languages), through the final subscript in the presidents array. Remember, the triple dot stops before executing the final number, which is why it doesn't count to 6. If you had wanted it to count to 6 (which in this case would have walked off the end of the array), you would have used the double dot. The output of the preceding

code follows:

Now lets list the presidents backwards

lets list the presidents backwards by calculating the array's subscript as the array's length minus the counter, minus one. Ugly, but it gets the job done:

The preceding program produces the following output:

Ruby has a much nicer way of iterating backwards

through a list: Negative subscripts. The following iterates backward through the array, using the fact that array[-1] is the last item, array[-2] is the second to last, etc:

If you're familiar with C, Pascal or Perl, you're probably dissappointed you couldn't just use presidents.length...0. Backwards iteration doesn't work in Ruby -- it must iterate up.

Iterators and Blocks

Another way to loop through an array is to use an iterator (in red in the following code) and a block (in blue in the following code:

In the preceding code, the block argument (prez) contains the current array element, and everything else until the closing brace contains code to operate on the block argument. The block argument is always enclosed in vertical lines (pipe symbols). The following is the output of the preceding code:

The block needn't be on one line:

As shown in the previous examples, you can define the block by enclosing it in curly braces. You can also define it by enclosing it in a do and an end, where the do replaces the opening brace, and the end replaces the closing brace:

Personally, I greatly prefer the do/end syntax for multiline blocks, because as a Perl/C/C++ guy I have a very different perception of braces than their limited use in Ruby, and also because of all the brace placement religious wars I've endured (I'm a Whitesmith type guy myself). However, on short single line blocks, using the braces saves valuable line space. From what I understand, the methods are interchangeable in features and performance, with one small exception...

Speaking of performance, if you declare the block argument outside the block (in other words, make it a local variable), performance improves because Ruby needn't recreate a variable every iteration. HOWEVER, the loop messes with the value of the variable, so it's best to use a specific variable for that purpose, and do not use it for other purposes within the subroutine. Here's an example of using a local variable as a block argument:

If you use a local variable for a block argument, do so only in loops with huge numbers of iterations, and use only variables that are specifically intended to serve as block arguuments and nothing else.

A Difference Between {} and do/end

As mentioned, there's one small difference between brace enclosed blocks and do/end enclosed blocks: Braces bind tighter. Watch this:

The braces bound tightly like this:

puts (my_array.collect {|word| word.capitalize})

Whereas do/end bind more loosely, like this:

puts (my_array.collect) do |word| word.capitalize} end

Note that the latter represents a syntax error anyway, and I've found no way to coerce do/end into doing the right thing simply by using parentheses. However, by assigning the iterator's results to a new array, that array can be used. It's one more variable and one more line of code. If the code is short, use braces. If it's long, the added overhead is so small a percentage that it's no big deal:

Generally speaking, if you want to directly use the result of iterators, use braces. For longer blocks, do/end is more readable, and the overhead for the extra variable and line of code is trivial.

while Loops

All the loops previously discussed looped through either an array or a set of numbers. Sometimes you need a more generic loop. That's when you use a while loop:

The first while loop iterated from 4 down to 1, quitting when ss became 0 and hit the while condition. The second loop was intended to iterate up to 4 and quit when 5 was encountered, but a break statement inside the loop caused it to terminate after printing 2 and then incrementing to 3. This demonstrates the break statement.

The third loop was intended to loop from 5 down to 1, quitting after printing 1 and then decrementing. However, the statement in the body of the loop added 5 when it reached 1, pushing it back up to 6, so it had to count down again. On the second countdown, the numbers were even, so it didn't trigger the if statement. This shows that unlike Pascal, it's OK to tamper with the loop variable inside the loop.

4 - RUBY BRANCHING

Let's count to 10...

Looping is one type of flow control in pure procedural languages. The other is branching. The following program implements an array called democrats and another called republicans . Depending on the command line argument, the program prints either the democratic presidents since 1974, the republican presidents since 1974, or an appropriate error message.

Note the if, elsif, else and end keywords, and how they delineate the branching. Note also the democrats.each syntax, which is a very shorthand way of iterating through an array, assuming what you want to do to each element can be stated succinctly.

One last note. The error handling in the preceding would be much better handled by exceptions, but they haven't been covered yet.

Like Perl, the if keyword can follow the action instead of preceding it:

The preceding is a very contrived program to showcase using the if keyword after the action. Note the following:

The if keyword must be on the same line as the action
Only a single action can precede the if keyword. Multiple actions separated by semicolons will do quite unexpected things.

5 - RUBY CONTAINERS

Containers are entities that contain other entities. Ruby has two native container types, arrays and hashes. Arrays are groups of objects ordered by subscript, while hashes are groups of key->value pairs. Besides these two native container types, you can create your own container types.

6 - RUBY ARRAYS

You've already seen how to initialize an array and how to use the each method to quickly iterate each element:

Now let's manipulate the array, starting by deleting the last three presidents:

The pop method deletes the final element. If you were to assign the pop method to a variable, it would store that last element and then delete it from the array. In the preceding code, you pop the last three presidents. Here is the result:

Now let's prepend the previous three presidents, Kennedy, Johnson and Nixon:

The result is as expected:

However, you might not like the idea of prepending in the reverse order. In that case, prepend all three at once:

Ruby arrays have methods shift, unshift, push, and pop:

method	action	argument	returns
push	Appends its argument to the end of the array.	Element(s) to be appended to end of the array.	A string consisting of the concatination of all non-nil elements in the array AFTER the action was taken.
pop	Returns the last element in the array and deletes that element.	None.	The last element of the array.
shift	Returns the first element of the array, deletes that element, and shifts all other elements down one location to fill its empty spot.	None.	The first element in the array.
unshift	Shifts all elements of the array up one, and places its argument at the beginning of the array.	Element(s) to be prepended to start of array.	A string consisting of the concatination of all non-nil elements in the array AFTER the action was taken.

You can assign individual elements of an array:

The preceding code produces this output:

The length of the array is the determined by the last initialized element, even if that element was initialized to nil. That can be very tricky, especially because if you read past the end of the array it returns nil. Be careful.

You can insert an element by assignment, as shown in the preceding code. If you assign to an element that already exists, you simply change its value, as we changed "Adams" to "John Quincy Adams".

Another thing you can do is get a slice of an array.

In the preceding, we have extraneous elements "buckle", "my" and "shoe", which we want to delete. So we replace element 2, for a count of 4 (element 2 and the next 2, in other words), to an empty array, effectively deleting them. The result follows:

Next, let's replace three numeric representations with their spelled out equivalents, plus add in another element we had forgotten:

You can see we deleted the three numerics, and then added the four spelled out versions in their place. Here's the output:

But what if you don't want to replace anything -- what if you just want to insert in the middle? No problem -- use 0 for the count...

The only trick here is that if you are not deleting the starting point element, the insertion will occur AFTER the starting element. Here is the output:

You might ask yourself what to do if you need to append before the first element, given that slice type insertion inserts AFTER the starting point. The simplest answer is to use the unshift method.

You can construct an array using a parenthesized range:

Finally, remembering that Ruby is intended to be an object oriented language, let's look at some of the more common methods associated with arrays (which are really objects in Ruby):

The Array.new method types numbers as an array. You could have done the same thing with numbers=[]. The next line assigns text three to the element with subscript 3, thereby setting the element and also setting the array's length. The next line sets the element whose subscript is 4 to nil, which, when you view the output, will prove that the length method returns one plus the last initialized element, even if it's initialized to nil. This, in my opinion, could cause trouble.

The class method returns the variable's class, which in a non-oop language could be thought of as its type. The following is the output:

We've gone through arrays in great detail, because you'll use them regularly. Now it's time to review Ruby's other built in container class...

7 - RUBY HASHES

There are two ways to think of a hash:

A set of key->value pairs
An array whose subscripts aren't necessarily ordered or numeric

Both of the preceding are correct, and do not conflict with each other.

In the preceding, we initialized the hash with three elements whose keys were lname, fname and ssno. We later added a fourth element whose key was gender, as well as correcting the value of ssno. The class and length methods do just what we'd expect, given our experience from arrays. This hash could be thought of as a single row in a database table. Here is the result:

Better yet, hashes values can be other types of classes. For instance, consider a hash of hashes:

Here's the output:

Basically, you just implemented the equivalent of a database table, whose rows correspond to Litt, Matsumoto and Torvalds, and whose columns are lname, fname and job. There are probably a dozen better ways to actually print this information, but at this point I'm still learning Ruby, so I did it with a distinctively Perl accent. Perhaps that's a good thing -- it proves that Ruby follows ordinary programming logic in addition to its many wonderful features.

Sorting Hashes

You sort hashes by converting them to 2 dimensional arrays -- an array of key/value pairs, and then sorting them. The sort method does just that. Here's an example:

#!/usr/bin/ruby -w

h = Hash.new
h['size'] = 'big'
h['color'] = 'red'
h['brand'] = 'ford'

av = h.sort{|a,b| a[1] <=> b[1]}
ak = h.sort{|a,b| a[0] <=> b[0]}
ak.each do
	|pair|
	print pair[0]
	print "=>"
	print pair[1]
	puts
end
puts "=============="
av.each do
	|pair|
	print pair[0]
	print "=>"
	print pair[1]
	puts
end

[slitt@mydesk ~]$ ./test.rb
brand=>ford
color=>red
size=>big
==============
size=>big
brand=>ford
color=>red
[slitt@mydesk ~]$

Notice that often a simple <=> command does not suffice, and you actually need to write your own function to establish collation order. Simply write a function taking two arguments (a and b) that returns 1 when a is superior to b, -1 when a is inferior to b, and 0 when they are equivalent.

Tests and Info Requests on Hashes

method	what it does	synonyms
has_key?(key)	Tests whether the key is present in the hash.	include?(key), key?(key) and member?(key)
has_value?(value)	Tests whether any element of the hash has the value, returning true or false.	value?(value)
index(value)	Returns the key for an element with the value. I don't know what happens if multiple elements have that value.
select {\|key, value\| block} => array	Returns an array of key/value pairs for which block evaluates true: h.select {\|k,v\| v < 200}
empty?	Returns True if no key/value pairs
inspect	Return contents of the hash as a string
invert	Returns a new hash with keys and values switched.
length	How many key/value pairs does it have?	size()
sort {\| a, b \| block } => array

8 - RUBY STRINGS

Strings are a class that ship with Ruby. The String class has a huge number of methods, such that memorizing them all would be futile. If you really want a list of them all, go but don't say I didn't warn you.

What I'd like to do here is give you the 10% of strings you'll need for 90% of your work. By the way, Ruby has regular expressions, and that will be covered in the following section. This section covers only Ruby's String class methods.

Let's start with string assignment and concatination:

The double less than sign is a Ruby String overload for concatination. If all goes well, we'll change the original string but the copy won't change. Let's verify that:

Oh, oh, it changed them both. String assignment copies by reference, not by value. Do you think that might mess up your loop break logic?

Use the String.new() method instead:

Here's the proof that it works the way you want it:

One really nice thing about the Ruby String class is it works like an array of characters with respect to splicing: #!/usr/bin/ruby myname = "Steve was here" print myname[6, 3], "\n" myname[6, 3] = "is" print myname, "\n"

[slitt@mydesk slitt]$ ./string.rb was Steve is here [slitt@mydesk slitt]$

This gets more powerful when you introduce the index string method, which returns the subscript of the first occurrence of a substring:

In the preceding, the start point for replacement was the return from the index method, and the count to replace is the return from the length method (on the search text). The result is a generic replacement:

Naturally, in real life you'd need to add code to handle cases where the search string wasn't found.

You already saw in-place concatenation with the << method, but in addition there's the more standard plus sign concatenation:

If the addition sign means to add strings together, it's natural that the multiplication sign means string together multiple copies:

Do you like the sprintf() command in C? Use the % method in Ruby:

You can compare strings:

Here are some other handy string methods:


mystring.capitalize	Title case. Returns new string equal to mystring except that the first letter of every word is uppercase
mystring.capitalize!	Title case in place.
mystring.center(mynumber)	Returns a new string mynumber long with mystring centered within it. If mynumber is already less than the length of mystring, returns a copy of mystring.
mystring.chomp	Returns a new string equal to mystring except any newlines at the end are deleted. If chomp has an argument, that argument serves as the record separator, replacing the default newline.
mystring.chomp!	Same as chomp, but in place. Equivalent of Perl chomp().
mystring.downcase	Returns new string equal to mystring but entirely lower case.
mystring.downcase!	In place modifies mystring, making everything lower case.
mystring.reverse	Returns new string with all characters reversed. IOWA becomes AWOI.
mystring.reverse!	Reverses mystring in place.
mystring.rindex(substring)	Returns the subscript of the last occurrence of the substring. Like index except that it returns the last instead of first occurrence. This method actually has more options, so you might want to read the documentation.
mystring.rjust(mynumber)	Returns a copy of mystring, except the new copy is mynumber long, and mystring is right justified in that string. If mynumber is smaller than the original length of mystring, it returns an exact copy of mystring.
mystring.split(pattern, limit)	Returns a new array with parts of the string split wherever pattern was encountered as a substring. If limit is given, returns at most that many elements in the array.
mystring.strip	Returns a new string that is a copy of mystring except all leading and trailing whitespace have been removed.
mystring.to_f	Returns the floating point number represented by mystring. Returns 0.0 if it's not a valid number, and never raises exceptions. Careful!
mystring.to_i	Returns an integer represented by mystring. Non-numerics at the end are ignored. Returns 0 on invalid numbers, and never raises exceptions. Careful!
mystring.upcase	Returns a new string that's an uppercase version of mystring.
mystring.upcase!	Uppercases mystring in place.

There are many, many more methods, but the preceding should get you through most programming tasks. If you end up using Ruby a lot, it would help to learn all the methods.

A word about mystring.split(pattern). What about the reverse -- turning an array into a string? Try this:

Here's a version that turns it into a comma delimited file with quotes:

You now know most of the Ruby string techniques you need for the majority of your work. Well, except for regular expressions, of course...

9 - RUBY REGULAR EXPRESSIONS

NOTE

This section assumes you understand the concept of regular expressions. If you do not, there are many fine regular expression tutorials on the web.

Regular expressions make life so easy, often replacing 100 lines of code with 5. Perl is famous for its easy to use and intuitive regular expressions.

Ruby is a little harder because most regular expression functionality is achieved by a regular expression object that must be instantiated. However, you CAN test for a match the same as in Perl:

Here's the code to actually retrieve the first match of /w.ll/ in the string:

This was almost just like Perl. You put parentheses in the regular expression to make a group, perform the regular expression search with the =~ operator, and then the match for the group is contained in the $1 variable. If there had been multiple groups in the regular expressions, matches would have also been available in $2, $3, and so on, up to the number of groups in the regular expression.

The more OOPish method of doing all this is to instantiate a new Regexp object and using its methods to gain the necessary information:

If you change /w.ll/ to /z.ll/, which of course does not match because there's not a "z" in string1, the output looks like this:

The preceding example shows how to do complete regex in Ruby. Start by creating a regular expression object using Regexp.new(). Then use that object's match method to find a match and return it in a MatchData object. Test that the MatchData object exists, and if it does, get the first match (matchdata[0]). The reason we also printed matchdata[1] was to show that, in the absense of groups surrounded by parentheses, the match method returns only a single match. Later you'll see a special way to return all matches of a single regular expression.

Another thing to notice is that, in Ruby, matching is not greedy by default. It finds the shortest string that satisfies the regular expression. If Ruby's matching was greedy like Perl's, the match would have included the entire string:

"will drill for a well in walla wall"

In other words, it would have returned everything from the first w to the last double l. Ungreedy matches go along with Ruby's principle of least surprise, but sometimes what you want is greedy matching.

You can return several matches using multiple groups, like this:

Note the different behavior when you use parentheses. Here you see that the 0 subscript element matches the entire regular expression, while elements 1, 2 and 3 are the individual matches for the first, second and third parenthesized groups.

What if you wanted to find ALL the matches for /w.ll/ in the string, without guessing beforehand how many parentheses to put in? Here's the way you do it:

What you've done here is repeated the match, over and over again, each time assigning the remainder of the string after the match to string1 via the post_match method. The loop terminates when no match is found.

Regex Substitution

My research tells me Ruby's regular expressions do not, in and of themselves, have a provision for substitution. From what I've found, you need to use Ruby itself, specifically the String.gsub() method, to actually perform the substitution. If that's true, to me that represents a significant hassle, although certainly not a showstopper. If I'm wrong about this, please let me know.

The following makes all occurrences of /w.ll/ uppercase in the string:

The preceding depends on the block form of the String.gsub() method. I could not get the non-block form to accept the matches of the regular expression.

If you had wanted to replace only the first occurrence of /w.ll/, you would have had to do this (warning, ugly!):

Being a Perl guy, I'm used to having the regular expression do the entire substitution in a single line of code, and find the preceding quite cumbersome. Obviously, some of the preceding code was inserted just for readability. For instance, I could have done this:

Or even this, which I'm sure would have fit right in with K&R first edition:

#!/usr/bin/ruby string1 = "I will drill for a well in walla walla washington." match = /w.ll/.match(string1) string1[/w.ll/.match(string1).offset(0)[0].../w.ll/.match(string1).offset(0)[1]] = match[0].upcase puts string1

If you can read the preceding, you're a better programmer than I.

In my opinion, Ruby beats the daylights out of Perl in most aspects, but not in regular expressions.

10 - RUBY REGULAR SUBROUTINES

A subroutine starts with def and ends with a corresponding end. Subroutines pass back values with the return keyword. In a welcome change from Perl, variables declared inside a subroutine are local by default, as shown by this program:

In the preceding, note that the puts command writes the string and then prints a newline, as opposed to the print command, which doesn't print a newline unless you add a newline to the string being printed.

If the howIfeel variable inside subroutine passback were global, then after running the subroutine, the howIfeel variable in the main program would change from "excellent" to good. However, when you run the program you get this:

The first and second printing of the howIfeel variable in the main program both print as "excellent", while the value passed back from the subroutine, and stored in variable mystring prints as "good", as we'd expect. Ruby's variables are local by default -- a huge encapsulation benefit.

You can pass variables into a subroutine as shown in the following code:

The value of num1 was not changed by running mult(), showing that arguments are passed by value, not reference, at least for integers. But what about for objects like strings?

Once again, manipulations of an argument inside the subroutine do not change the value of the variable passed as an argument. The string was passed by value, not reference.

11 - RUBY REGULAR EXCEPTIONS

Growing up with C, I wrote code for every possible error condition. Or, when I was too lazy to write code for error conditions, my code was less robust.

The modern method of error handling is with exceptions, and Ruby has that feature. Use them.

There are two things you can do: handle an exception, and raise an exception. You raise an exception by recognizing an error condition, and then associating it with an exception type. You usually don't need to raise an exception because most system calls already raise exceptions on errors. However, if you've written a new bit of logic, and encounter a forbidden state, then you would raise an exception.

You handle an exception that gets raised -- typically by system calls but possibly by your code. This handling is only for protected code starting with begin and ending with end. Here's a simple example:

The preceding code produces the following output:

However, if the filename in File.new() is changed to the nonexistent /etc/resolX.conf, the output looks like this:

Global variable $!i had the value "No such file or directory - /etc/resolX.con", so that printed along with the error message in the rescue section. This exception was then passed to other exception handlers, that wrote additional messages and eventually terminated the program.

Exceptions are implemented as classes (objects), all of whom are descendents of the Exception class. Some have methods over and above those of the Exception class, some do not. Here is a list of the exceptions I was able to find in documentation on the web:

ArgumentError
IndexError
Interrupt
LoadError
NameError
NoMemoryError
NoMethodError
NotImplementedError
RangeError
RuntimeError
ScriptError
SecurityError
SignalException
StandardError
SyntaxError
SystemCallError
SystemExit
TypeError

The following is a more generic error handling syntax:

In the preceding, variables mySyntaxError and myStandardError are local variables to store the contents of global variable $!, the exception that was raised.

Retry

There's a retry keyword enabling a retry on error. This is handy when performing an activity that might benefit from a retry (reading a CD, for instance):

Raising an Exception

Sometimes the neither the system nor the language detect an error, but you do. Perhaps the user input someone 18 years old for Medicare. Linux doesn't know that's wrong. Ruby doesn't know that's wrong. But you do.

You can raise a generic exception (or the current exception if there is one) like this: raise if age < 65

To raise a RuntimeError exception with your own message, do this:

raise "Must be 65 or older for Medicare"

To raise a RangeError exception (you wouldn't really do this), you'd do this:

raise RangeError, "Must be 65 or older for Medicare", caller [slitt@mydesk slitt]$ ./hello.rb ./hello.rb:3: Must be 65 or older for Medicare (RangeError) [slitt@mydesk slitt]$

Perhaps the best way to do it is to create a new exception class specific to the type of error:

Now let's combine raising and handling, by creating a subroutine called signHimUp(), which raises the exception, and the calling main routine, which handles. In this particular, rather contrived program, information about the person whose information raised the exception is stored in the exception itself, by the initialize() method, which assigns its arguments to the class's instance variables, so that this call:

myException = MedicareEligibilityException.new(name, age)

creates an instance of class MedicareEligibilityException whose instance variables contain the person's name and age for later reference. Once again, this is very contrived, but it illustrates some of the flexibility of exception handling:

#!/usr/bin/ruby
class MedicareEligibilityException < RuntimeError
	def initialize(name, age)
		@name = name
		@age = age
	end
	def getName
		return @name
	end
	def getAge
		return @age
	end
end

def writeToDatabase(name, age)
	# This is a stub routine
	print "Diagnostic: ", name, ", age ", age, " is signed up.\n"
end

def signHimUp(name, age)

if age >= 65
		writeToDatabase(name, age)
	else
		myException = MedicareEligibilityException.new(name, age)
		raise myException , "Must be 65 or older for Medicare", caller
#		raise MedicareEligibilityException , "Must be 65 or older for Medicare", caller
	end
end

# Main routine
begin
	signHimUp("Oliver Oldster", 78)
	signHimUp("Billy Boywonder", 18)
	signHimUp("Cindy Centurinarian", 100)
	signHimUp("Bob Baby", 2)

rescue MedicareEligibilityException => elg
	print elg.getName, " is ", elg.getAge, ", which is too young.\n"
	print "You must obtain an exception from your supervisor. ", elg, "\n"
	
end

print "This happens after signHimUp was called.\n"

In the preceding code, the main routine calls subroutine signHimUp for each of four people, two of whom are underage. The begin/rescue/end structure in the main routine allows exceptions of type MedicateEligibilityException to be handled cleanly, although such exceptions are raised by the called subroutine, signHimU(). , signHimU(). routine tests for age 65 and older, and if so, calls dummy writeToDatabase() and if not, creates a new instance of MedicateEligibilityException containing the person's name and age, and then raises that exception, with the hope that the calling routine's exception handling will be able to use that information in its error message.

The MedicateEligibilityException definition itself is a typical class definition, with instance variables beginning with @, an initialize() constructor that assigns its arguments to the instance variables, and get routines for the instance variables. All of this will be covered later when we discuss classes and objects.

Here is the result:

As you can see, the first call to signHimUp() successfully ran the stub write to database routine, as indicated by the diagnostic line. The next call to signHimUp() encountered an exceptio MedicateEligibilityException exception, and the code in the rescue block got the patient's name and age from the exception, and wrote it. At that point the begin block was terminated, and execution fell through to the line below the end matching the exception handling's begin. If we had wanted to, we could have terminated the program from within the rescue block, in many ways, including ending that block with a raise command, or to bail immediately, an exit command.

Catch and Throw

The catch and throw keywords enable you to jump up the error stack, thereby in effect performing a goto. If you can think of a good reason to do this, research these two keywords on your own. Personally, I'd prefer to stay away from them.

We've just scratched the surface of exception handling, but you probably have enough now to at least write simple exceptions and read other people's exception code.

12 - RUBY TERMINAL IO

This section will cover just a few of the many ways you can do terminal IO. You've already learned about print and puts:

Ruby has a printf() command similar to C:

You get line oriented keyboard input with gets:

You can get a single character with gets(). However, the user will need to press the Enter key before gets() will accept the character. To enable instantaneous recognition of the character, you must set cbreak before gets() and then reset it afterwards, like this:

#!/usr/bin/ruby print "Character please=>" system "stty cbreak </dev/tty >/dev/tty 2>&1"; int = STDIN.getc system "stty -cbreak </dev/tty >/dev/tty 2>&1"; print "\nYou pressed >", int, "<, char >", int.chr, "<\n"

The cbreak commands seem to work on modern Linuces. They are VERY system dependent, and as far as I know don't work on Windows at all. On some Unices you might try these instead:

system "stty", '-icanon', 'eol', "\001";
int = STDIN.getc
system "stty", 'icanon', 'eol', '^@'; # ASCII null
Terminal I/O is pretty simple in Ruby. So is file I/O...

13 - RUBY FILE IO

File I/O uses the File object. It's very straightforward, as you can see from the following program, which opens resolv.conf for input, andjunk.jnk for output, and then copies each line from the input file to the output file:

Perl has a way to immediately read a whole file into an array, and so does Ruby:

Ruby can no also read one character at a time:

If for some reason you don't want to use the each construct, you can use readchar like this:

In the preceding code, the eof method looks ahead to see whether the next character read will be valid, and if so, loops through, reads and prints it. You might think of doing a priming read, then putting the next read at the bottom of the loop, testing for i==nil. Unfortunately, if you read into the end of file, it triggers an exception which prints an error message, and nobody wants that. Instead, use eof to look ahead and read just enough.

It isn't demonstrated in this tutorial, but you can use readline to read a line at a time, again using eof to look ahead.

14 - RUBY HOW OOP IS RYBY?

You hear it all the time. "Ruby's a purely Object Oriented language!"

On some levels that's a true statement, but it's misleading. It misled me into staying away from Ruby for three years.

See, to me "purely OOP" means a language you can't write procedural code with. Java, for instance, where you need to create a class to write a "hello world" program, and you can't make a subroutine outside of a class.

Ruby's not like that. A Ruby "hello world" program is two lines, you can write subroutines outside of any class that are accessible anywhere, and if you'd like you can write complete and complex programs without creating a single class or object.

In Ruby's case, what they mean by "purely OOP" is that all variables are objects. Integers, floating point numbers, characters, strings, arrays, hashes, files -- they're all objects. You manipulate these objects with their methods, not with Ruby built in operators. For instance, in the following:

profit = revenue - expense

In the preceding, profit, revenue and expense are all objects of class Float. The minus sign (-) is not a Ruby operator -- it's a method of the Float class. In the C language, the minus sign would be an operator supplied by the language, but in Ruby it's just a method of the Float class.
Incidentally, a plus sign method is implemented in class Fixnum integers, where once again it adds the value, and in the String class, where it concatinates strings.

So Ruby's "purely OOP" in that when you use it you'll definitely be using objects, but you do not need to create objects to write a substantial Ruby programmer. So if you do not consider yourself an Object Oriented programmer, or even if you hate OOP, don't let that stop you from using Ruby.

15 - RUBY OBJECT ORIENTED PROGRAMMING CONCEPTS

In my opinion, objects are all about data. In programs using objects to simulate real world things like cannonballs, such data might be position, velocity and mass. In business programs, an object might contain a person's first and last name, employee number, job classification and health insurance.

An object is a wonderful place to store a program's configuration information. All such info is kept in one place such that only a single object is kept global or passed in and out of subroutines.

All of these ideas precede object orientation. Since the dawn of time programmers have put all data for an entity in a data structure, and then manipulated the structure. Here's some code I wrote in 1986 to manipulate the page of a dot matrix printer. Keep in mind that back in those days, computers didn't have enough RAM for everyone to store their printed page in an 80x66 array. Much of my job back then was programming computers to print out medical insurance forms, each with about 40 boxes to fill out in very tight quarters. There were several different form layouts, and they changed frequently. So here's some 1986 C code (note the original K&amo;R style -- no prototypes):

/* THE REPORT VARIABLE */
typedef struct
   {
   FILE *fil;          /* report file file variable */
   int y;              /* y coord on page, changed only by atyxpr */
   int x;              /* x coord on page, changed only by atyxpr */
   int pglength;       /* lines per page, changed only by openrpt */
   int stringlength;   /* maximum length of string to be printed */
   int lineno;         /* line number, changed only by applcatn pgmr */
   int pageno;         /* page number, changed only by applictn pgmr */
   char status[10];    /* set to @REPORT or @CLOSED */
   } REPORT;

void atyxpr(rpt,y,x,st)
  REPORT *rpt;     /* the report variable pointer */
  int y;           /* the present vertical print position */
  int x;           /* the present horizontal print position */
  char *st;        /* the string to be printed */

{
  int i;

checkopen(rpt);
  if ((x == 0) && (y == 0))
     {            /* continue printing at last position */
     y = rpt->y;
     x = rpt->x;
     }

/* formfeed if the print line you're seeking is higher than the last time */
  if (y < rpt->y)
     formfeed(rpt);

/* insert a '^' if you've overwritten a column */
  if ((y == rpt->y) && (x < rpt->x))
     {
     strcpy(st, st +(1 + rpt->x - x));
     writestring(rpt, "^");
     x = rpt->x;
     fprintf(stderr, "?-warning-atyxpr- column overwrite in line %d.\n", rpt->y);
     }

/* bring the print position to the new coordinates */
  while (y > rpt->y)
        {
        linefeed(rpt->fil);
        rpt->y = rpt->y + 1;
        rpt->x = 1;
        }
  while (x > rpt->x)
        {
        spaceout(rpt->fil);
        rpt->x = rpt->x + 1;
        }

/* do the actual write of the string */
  writestring(rpt, st);

/* bring the x position up to date after the write */
  rpt->x = rpt->x + strlen(st);
}

The REPORT structure kept track of the current position of the print head (y and x), the number of lines on a page (pglength), and the file to which to write the output (the file was usually a printer device). All this information remained persistent in the report structure.

The report structure was manipulated by a function called atyxpr(),. To print a string at a specific line and column, the programmer specified the string to print and the y and x coordinates (row and column) at which to start printing the string. Also specified was the report structure.

If the row and column were specified as both being 0, atyxpr() printed the string at the current print head position, as if the print was done by a simple printf().

If the row was the same as the current printhead row but the column was farther out, atyxpr() printed spaces until the printer head was in the desired place, and then the string was printed.

If the desired row was below the current printhead position, atyxpr() printed linefeeds to get to the desired row, printed spaces to get to the desired column, and then printed the string.

If the desired row was above the current printhead position, that meant that it needed to be printed on the next page, so a formfeed was issued, then enough linefeeds to get to the desired row, then enough spaces to get to the desired column, and then the string was printed.

What does this have to do with Ruby? Believe it or not, there's a purpose to showing this obsolete C code from an era of monospace printers and computers too anemic to store 80x66 worth of characters. That purpose is to show that there's absolutely nothing new about congregating all data about a specific entity or device in a single place, nor is there anything new about encapsulation. You do not need object orientation to do these things. I did it in 1986 using K&R C, and people were doing it long before me.

What IS new about object oriented programming (OOP) is that you can store the subroutines that manipulate the data (atyxpr() in this example) right along with the data. But so what? What's the advantage?

The advantage is something called namespace collision. The name of the subroutine manipulating the data is in scope only within the context of that data. If that name is used elsewhere, it refers to a different subroutine. In old C, if you had geometric figures square, circle, point and parabola, look what you'd need:

circle_move(circleVar, fromy, fromx, toy, tox)

square_move(squareVar, fromy, fromx, toy, tox)

point_move(parabolaVar, fromy, fromx, toy, tox)

parabola_move(parabolaVar, fromy, fromx, toy, tox)

You need to remember four subroutine names (circle_move, square_move, point_move, and parabola_move), none of which is especially memorable. Now consider an object oriented language, where objects circle, square, point and parabola each implement their own move routine:

circle.move(fromy, fromx, toy, tox)

square.move(fromy, fromx, toy, tox)

point.move(fromy, fromx, toy, tox)

parabola.move(fromy, fromx, toy, tox)

In Object Oriented Programming (OOP), move means move -- it's intuitive.

Others will state additional benefits. They'll tell of the ability to redefine operators depending on the types being manipulated. They'll speak of inheritance, where you can create a new object type that's an enhancement of one already made, and you can even create a family of similar object types that can be manipulated by same named, similar performing subroutines. These are all nice, but in my opinion the only essentials are encapsulation and reduction of namespace collision.

Many tout OOP for purposes of reusability. I disagree. Everyone's talking about reusable code, but few are writing it, with OOP or anything else. Reusability is harder to find than the fountain of youth. If OOP were really that reusable, that wouldn't be true.

Classes and Objects

Think of a class as a set of architectural drawings for a house. Think of objects as the houses built according to those drawings. The drawings can be used as a plan for many, many houses. Not only that, the houses needn't be the same. Some can have carpeting, some have wood floors, but they were all created from the drawings. Once the house is created, the owner can put in a 14 cubic foot refrigerator or a 26 foot one. The owner can put in the finest entertainment center, or a 14" TV with rabbit ears on a wooden crate. No matter, they were all made from the same drawings. The drawing is the class, the house is the object.

A class is a plan to create objects. Ideally it lists all the data elements that will appear in any of its objects. It lists any subroutines the objects will need to manipulate the data. Those subroutines are called methods in OOP speak. It might even give the data elements initial values so that if the programmer doesn't change them, he has intelligent defaults. But typically, the computer program changes at least some of those data elements while it's being run.

16 - RUBY SIMPLE OOP IN RYBY

In Ruby, a class begins with the class keyword, and ends with a matching end. The simplest class that can be made contains nothing more than the class statement and corresponding end:

class Myclass
end

The preceding class would not error out, but it does nothing other than tell the name of its class:

To be useful, a class must encapsulate data, giving the programmer methods (subroutines associated with the class) to read and manipulate that data. As a simple example, imagine a class that produces objects that maintain a running total. This class maintains one piece of data, called @total, which is the total being maintained. Note that the at sign (@) designates this variable as an instance variable -- a variable in scope only within objects of this class, and persistent within those objects.

This class has a method called hasTotal() that returns true if the total is defined, false if it's nil. That way you can test to make sure you don't perform operations on a nil value. It also has getTotal() to read the total. It has setTo() to set the total to the argument of setTo(), it has methods increaseBy() and multiplyBy() add or multiply the total by an argument.

Last but not least, it has initialize()., which is called whenever Total.new() is executed. This happens because initialize() is a special reserved name -- you needn't do anything to indicate it's a constructor. The number of arguments in initialize() is the number of arguments Total.new() expects. The other thing that happens in initialize() is that all the instance variables are declared and initialized (in this case to the argument passed in through new().

Here is the code:

The main routine instantiates an object of type Total, instantiating the total to a value of 0. Then a loop repeatedly adds the loop subscript to the total, printing each time after the add. Finally, outside the loop, the total is printed, which is 10, otherwise known as 1+2+3+4.

Take some time to study the preceding example, and I think you'll find it fairly self-explanatory.

Now for a little controversy. Remember I said you declare all instance variables inside initialize()? You don't have to. You could declare them in other methods:

You and I know fname and lname are accessed as methods, but because they're read as steve.fname, it seems like you're directly reading the data. Now let's go for a read/write example:

When I instantiated the object in the preceding code, I accidentally spelled my name "Stove". So I changed it as if it were a variable. This behavior was facilitated by the def lname=(arg) method. The output of the preceding code follows:

The methods facilitating the seeming ability to write directly to the data are called accessor methods. Because accessor methods are so common, Ruby has a shorthand for them:

In the preceding code, the variables after attr_reader substituted for the readonly accessor members, while the attr_writer substituted for the writeonly accessor members. Notice that when you write the names of the instance variables, you substitute a colon for the instance variables' at signs. There is actually a syntax reason, consistent with Ruby, for this substitution, but I can't explain it, so I choose to just remember it.

Remember, this seeming direct access must be explicitly enabled by the class's programmer, so this usually doesn't compromise encapsulation beyond what needs to be available. In my opinion this is a really handy option.

Inheritance

Inheritance is where a more specific kind of class is made from a more general one. For instance, an employee is a kind of person. Specifically (and oversimplistically), it's a person with an employee number. See this inheritance example:

Ruby REALLY makes inheritance easy. On the class line you declare the child class's parent. In the child class's initialize() you call the parent's initializer by the super(supers_args) syntax. Because the parent's data is initialized and available to the child, you needn't redeclare accessor methods for the parent's data -- only for the child's data. In other words, in the child class you need code only for data specific to the child. It's handy, intuitive, and smooth.

Redefining Operators

It is nice to have total.add() and total.increaseBy() methods. But in many cases it's even more intuitive to use the + or += operator. In C++ it's always somewhat difficult to remember how to redefine operators. Not so in Ruby:

In the preceding, we define add() as returning the argument plus @total. Notice that @total is not changed in-place. We might want to add add a Total to the existing Total, or we might want to add an integer. Therefore, Total::add() checks the argument's type, and if it's a Total it adds the argument's value, otherwise it adds the argument.

With add() safely defined, we now define + as basically a synonym for add(). The fascinating thing about Ruby is that if you define +, you get += free of charge, without further coding, and += does the right thing. As of yet I have not found a way to redefine +=, or any other punctuation string more than one character long. Luckily, += "just does the right thing", consistent with the definition of +.

It's not necessary to define a word function before redefining an operator, as the * operator (really a method) in the preceding code shows. Once again, it has an if statement so that integers or Totals can be added.

In the main part of the routine, we test by creating three totals with values 5, 2 and 3 repectively. We then add them together to create myTotal, which should be 10 and indeed is. We then in-place multiply by 2 to get the expected 20, and then in-place add 10 to get the expected 30:

50-game

JAVA

Back

Home

1 - JAVA OVERVIEW

Conventions in These Notes

Code is listed in a monospace font, both for code examples and for Java keywords mentioned in the text.

The standard Java convention for names is used:

Class names are listed with an initial uppercase letter.
Variable and function names are listed with an initial lowercase letter.
The first letters of inner words are capitalized (e.g., maxValue).

For syntax definitions:

Terms you must use as is are listed in normal monospace type.
Terms that you must substitute for, either one of a set of allowable values, or a name of your own, or code, listed in italics.
The following generic terms are used - you must substitute an appropriate term.

`access`	An access word from: `public`, `protected`, `private`, or it can be omitted
`modifiers`	one or more terms that modify a declaration; these include the access terms as well as terms like: `static`, `transient`, or `volatile`
`dataType`	A data type word; this can be a primitive, such as `int`, or the name of a class, such as `Object`; variants of this include: `returnType` and `paramType`
`variableName`	The name of a variable; variants on this include `paramName` and `functionName`
`ClassName`	The name of a class; there will be variants of this used for different types of examples, such as: `BaseClassName`, `DerivedClassName`, `InterfaceName`, and `ExceptionClassName`
`code`	Executable code goes here
`. . .`	In an example, omitted code not related to the topic

The Java Environment - Overview

A Java program is run differently than a traditional executable program.

Traditional programs are invoked through the operating system.

They occupy their own memory space.
They are tracked as an individual process by the OS.

Traditional programs are compiled from source code into a machine and OS-specific binary executable file.

To run the program in different environments, the source code would be compiled for that specific target environment.

When you run a Java program, the OS is actually running the Java Runtime Engine, or JRE, as an executable program; it processes your compiled code through the Java Virtual Machine (usually referred to as the JVM).

A Java source code file is compiled into a bytecode file.

You can consider bytecode as a sort of generic machine language.
The compiled bytecode is read by the JVM as a data file.
The JVM interprets the bytecode at runtime, performing a final mapping of bytecode to machine language for whatever platform it is running on.
Thus, Java programs are portable - they can be written in any environment, compiled in any environment, and run in any environment (as long as a JVM is available for that environment).
The JVM manages its own memory area and allocates it to your program as necessary.
Although this involves more steps at runtime, Java is still very efficient, much more so than completely interpreted languages like JavaScript, since the time-consuming parsing of the source code is done in advance.

The Java Environment - Overview

A Java program is run differently than a traditional executable program.

Traditional programs are invoked through the operating system.

They occupy their own memory space.
They are tracked as an individual process by the OS.

Traditional programs are compiled from source code into a machine and OS-specific binary executable file.

To run the program in different environments, the source code would be compiled for that specific target environment.

You can consider bytecode as a sort of generic machine language.
The compiled bytecode is read by the JVM as a data file.
The JVM interprets the bytecode at runtime, performing a final mapping of bytecode to machine language for whatever platform it is running on.
Thus, Java programs are portable - they can be written in any environment, compiled in any environment, and run in any environment (as long as a JVM is available for that environment).
The JVM manages its own memory area and allocates it to your program as necessary.
Although this involves more steps at runtime, Java is still very efficient, much more so than completely interpreted languages like JavaScript, since the time-consuming parsing of the source code is done in advance.

Writing a Java Program

Java source code is written in plain text, using a text editor.

his could range from a plain text editor like Notepad, to a programmers' editor such as TextPad, EditPlus, or Crimson Editor, to a complex integrated development environment (IDE) like NetBeans, Eclipse, or JDeveloper.
The source code file should have a .java extension.

The javac compiler is then used to compile the source code into bytecode.

The bytecode is stored in a file with an extension .class
Bytecode is universal - one bytecode file will run on any supported platform.

You then run the java runtime engine, which will then interpret the bytecode to execute the program.

The executable program you are running is: java.
The class name tells the JVM what class to load and run the main method for.
You must have a JVM made specifically for your hardware/OS platform.

Obtaining the Java Environment

You can download the SDK (software development kit) including the compiler and runtime engine from Oracle at: . Look for the download of JavaSE 1.6.0.10 (or the latest release of that version).

You can also download the API documentation and even the source code. Note that:

he documentation lists all the standard classes in the API, with their data fields and methods, as well as other information necessary to use the class. You will find this documentation helpful as you work through some of the exercises.
You can view the docs online, but it is worth downloading it so that you don't have to be connected to the internet to use it.

Setting up Your Java Environment

Java programs are compiled and run from an operating system prompt, unless you have installed an IDE that will do this for you directly. If you create an applet, this would run inside a web page in a browser.

After you have installed the JDK, you will need to set at least one environment variable in order to be able to compile and run Java programs.

For more complex projects that pull together elements from different sources, you must set an additional environment variable or two. Note that:

a PATH environment variable enables the operating system to find the JDK executables when your working directory is not the JDK's binary directory.
CLASSPATH is Java's analog to PATH, the compiler and JVM use it to locate Java classes.
Often you will not need to set this, since the default setting is to use the JDK's library jar file and the current working directory.
But, if you have additional Java classes located in another directory (a third-party library, perhaps), you will need to create a classpath that includes not only that library, but the current working directory as well (the current directory is represented as a dot).
Many IDE's and servers expect to find a JAVA_HOME environment variable.
This would be the JDK directory (the one that contains bin and lib).
The PATH is then set from JAVA_HOME plus \bin.
This makes it easy to upgrade your JDK, since there is only one entry you will need to change

Best Practice: Setting PATH from JAVA_HOME

The procedure to permanently set the environment variables varies slightly from one version of Windows to another; the following will work in many, including Windows XP. The process for Vista is similar, but slightly different:

Right-click on My Computer.
Choose Properties.
Select the Advanced tab.
Click the Environment Variables button at the bottom.
Check both the User and System variable lists to see if JAVA_HOME or PATH already exist.
If JAVA_HOME exists, check to see that it matches your most recent JDK (or the one you wish to use).

It is probably better to set this as a System variable.
If it exists, click Edit, if not, click Add.
For the variable name, enter JAVA_HOME.
For the value, enter your JDK directory, such as C:\Program Files\Java\jdk1.5.0_14.

Note that the space in the name can sometimes cause problems.
One solution is to put quote marks around the entry, as in "C:\Program Files\Java\jdk1.5.0_14".
An even better solution would be to use the 8-character form of the directory name, such as C:\Progra~1\Java\jdk1.5.0_14 (you can check if this works in your system by typing it into the address bar of a My Computer window).

7. for PATH, again select either Add or Edit.

You could do this either as a User variable or a System variable.
If there isn't already a JDK bin directory mentioned in the PATH, it will work as a User variable.
If there is already a JDK mentioned, you would want to ensure that this new entry preceded the existing entry, so you would edit that variable.
Note that if the existing entry was created using JAVA_HOME, then we are already set correctly .
If you "prepend" an entry to PATH , it will be found first, and therefore supercede any other directory - if you append to path, your directory won't be found if an earlier entry JDK entry exists (the following image shows a prepend).
Also note that System variables precede User variables, so they will be found first.

Setting Environment Variables from a Command Prompt

If you set the variables from a command prompt, they will only hold for that session, but you could create a batch file that you could run each time you open a command prompt window.

To set the PATH from a command prompt or batch file:

If you need to set the CLASSPATH:

Early versions of the JDK required you to include the JDK's lib directory in the CLASSPATH; this is no longer necessary .
Note that UNIX environments use $PATH and $CLASSPATH instead of %PATH% and %CLASSPATH%, and that the path element separator is a colon instead of a semicolon.

Creating a Class that Can Run as a Program

The main() Method

In order to run as a program, a class must contain a method named main, with a particular argument list. This is similar to the C and C++ languages.

The definition goes inside your class definition, and looks like:

It must be public, because it will be called from outside your class (by the JVM).
The static keyword defines an element (could be data or functional) that will exist regardless of whether an object of a class has been instantiated. In other words, declaring main as static allows the JVM to call the method and therefore execute the program. That doesn't mean that an object of that class cannot be instantiated, it is just not required.
The String[] args parameter list states that there will be an array of String objects given to the method - these are the command line arguments.
To run the program, use the following from the command line if you are running it from the console:

For example, if we had an executable class called Hello, in a file called Hello.java that compiled to Hello.class, you could run it with:

Useful Stuff Necessary to Go Further

System.out.println()

In order to see something happen, we need to be able to print to the screen.

There is a System class that is automatically available when your program runs (everything in it is static).

it contains, among other things, input and output streams that match stdin, stdout, and stderr (standard output, standard input, and standard error).

System.out is a static reference to the standard output stream.

As an object, System.out contains a println(String) method that accepts a String object, and prints that text to the screen, ending with a newline (linefeed).

There is also a print(String) method that does not place a newline at the end.

You can print a String directly, or you can build one from pieces.

It is worth noting that a String will automatically be created from a quote-delimited series of characters.
Values can be appended to a String by using the + sign; if one item is a String or quote-delimited series of characters, then the rest can be any other type of data.

Using an Integrated Development Environment

Duration: 30 to 40 minutes. Integrated Development Environments, or IDEs, can greatly facilitate the task of creating applications. Mid-level code editors, such as Crimson Editor, TextPad, or Edit-Plus, provide syntax highlighting, automatic indenting, parentheses and curly-brace matching, and may have tools to compile and execute programs.

High-end environments, such as Eclipse, NetBeans, or JDeveloper, offer many additional features, such as project management, automatic deployment for web applications, code refactoring, code assist, etc. But, these additional capabilities come with the price of additional complexity in the environment, particularly because they force you to create projects for even the simplest applications.

To use the class files in these environments, we must first have a workspace, which is a collection of projects. Workspaces have various configuration settings that will cut across all projects within all projects they contain, such as which version of Java is in use, any added libraries, etc. (a project is usually one application).

Both Eclipse and NetBeans use the workspace concept, but you can start with any empty directory - the IDE will add its own special files as you create projects.

In the Windows Explorer, navigate to your ClassFiles directory. If it does not contain a Workspace subdirectory, create it.

To use Eclipse with the class files, you can direct it to the workspace (ClassFiles/Workspace) when it opens (if it asks), or use File, Switch Workspace if Eclipse is already running. Each chapter's demo folder should be treated as a project, as should each Solution folder.

One limitation of these environments is that no project can contain the same Java class twice, so our progressive versions of the Payroll application solution require their own individual project. Also, due to the way Java's package structures work, each Demo folder must be a separate project, as with each subdirectory under Solutions.

To use the Exercises folder as an Eclipse project:

Select File > New > Java Project
Enter Exercises for the project name
Click Finished
In the Package Explorer pane, right-click on the src folder under the Exercises folder
Select Import from the context menu
Select File System from the tree in the Select dialog box
Click Next
Using the Browse button, navigate to and select c:/ClassFiles/Exercises. (Note: this path might be different depending on where you extracted the class zip file)
Make sure the Exercises check box is selected and click Finished
Expand the src folder in the Package Explorer and then expand the default package folder
Right-click on the file Welcome.java
From the context menu select Run As... > Java Application
Note the output is displayed in the Console at the bottom of the Eclipse workbench

As we encounter each chapter, we can create a project using the Demos directory for that chapter the same way we just created the Exercises project..

To create a Java class within a project, use File, New , and then Class if that is available, or Other... and then Class . Provide a name and then OK .

In general, with the several applications that we will build upon progressively (Game and Payroll), you can continue to work with the same files, and add to them as we cover additional topics. If you want to check the solutions, you can either open those files in a separate editor, like Notepad, or create a project for that Solutions subdirectory. If you wish to save a particular stage of the application for future reference, you can just make a copy of the Exercises directory.

The examples and instructions provided use a more basic text editor (Chrimson) and an OS console for clarity. You are free to choose which tool to use. If Eclipse becomes a problem, move to a simple editor. The focus of this course is on the Java Programming Language and not a particular tool.

First Java Program

Duration: 5 to 15 minutes.

1.Create a file called Hello.java.
2.Enter the following code:

3.Save the file.
4.In a command prompt window, change to the directory where Hello.java is stored and type the following:

A prompt on the next line without any error messages indicates success.

5.Type:

6.Press Enter.

You should see the message Hello World print in the window.

All Java code must be within a class definition.
A class defines a type of object.
A public class can be accessed by any other class.
A public class must be in its own file, whose name is the name of the class, plus a dot and an file extension of java(e.g., Hello.java ).

Curly braces denote a block of code (the code inside the braces).
Code within braces usually belongs to whatever immediately precedes them.

Words followed by parentheses denote a function.
To be executable by itself, a class must have a function defined in this fashion; the name main means that execution will start with the first step of this function, and will end when the last step is done.
It is public because it needs to be executed by other Java objects (the JVM itself is a running Java program, and it launches your program and calls its main function).
It is static because it needs to exist even before one of these objects has been created.
It does not return an answer when it is done; the absence of data is called void.
The String[] args represents the additional data that might have been entered on the command line.

System is an class within the JVM that represents system resources.
It contains an object called out, which represents output to the screen (what many environments call standard out).
Note that an object's ownership of an element is denoted by using the name of the object, a dot, and then the name of the element.
out in turn contains a function, println, that prints a line onto the screen (and appends a newline at the end).
A function call is denoted by the function name followed by parentheses; any information inside the parentheses is used as input to the function (called arguments or parameters to the function).
The argument passed to println() is the string of text "Hello World!".
Note that the statement ends in a semicolon (as all do Java statements).

Using the Java Documentation

Sun provides extensive documentation of the API (library of available classes). The documentation for version 6 is available at

If you view that page, you will see a list of classes on the left as hyperlinks. Clicking a class name will bring up the documentation for that class on the right.

For example, click on System. The page on the right contains documentation on the elements of the class, categorized by type of element (there are links at the top for fields, constructors, methods, etc.).

Try to locate the out field - note that the field types, parameter types and return types are hyperlinked, and that out is a PrintStream. Click that, and find the println methods in a table with short descriptions. Select one to see the detailed description. The multiple versions are an example of method overloading, which we will cover in an upcoming lesson. Another lesson will cover documenting your own classes with the same tool that created this documentation.

In this lesson, you have learned:

2 - JAVA SYNTAX

General Syntax Rules

ava is case-sensitive. main(), Main(), and MAIN() would all be different methods.

There are a limited number of reserved words that have a special meaning within Java. You cannot use these words for your own variables or methods.

Some examples of reserved words are:

public
void
static
do
for
while
if

Most keyboard symbol characters (the set of characters other than alphabetic or numeric) have a special meaning.

Names may contain alphabetic characters, numeric characters, currency characters, and connecting characters such as the underscore ( _ ) character:

Names may not begin with a numeric character.
Note that the set of legal characters draws from the entire Unicode character set.
Also note that it is probably impossible to write a succinct set of rules about what are valid characters, other than to say a character, that when passed to Character.isJavaIdentifierPart(char ch), results in a true value.

The compiler parses your code by separating it into individual entities called tokens or symbols in computer science jargon:

Names (of classes, variables, and methods).
Command keywords.
Single or compound symbols (compound symbols are when an operation is signified by a two-symbol combination).

Tokens may be separated by spaces, tabs, carriage returns, or by use of an operator (such as +, -, etc.).

Since names may not contain spaces, tabs, carriage returns, or operator characters, these characters imply a separation of what came before them from what comes after them.

Extra whitespace is ignored. Once the compiler knows that two items are separate, it ignores any additional separating whitespace characters (spaces, tabs, or carriage returns).

Java Statements

A Java statement is one step of code, which may span across multiple lines.

Java statements end with a semicolon (the ; character).

It is OK to have multiple statements on a single line.

Program execution is done statement by statement, one statement at a time from top to bottom (if there is more than one statement on a line, execution goes from left to right).

Within a statement, execution of the individual pieces is not necessarily left to right. There are concepts called operator precedence and associativity that determine the order of operations within a statement.

Blocks of Code

A block of code:

Is enclosed in curly braces - start with { and end with }.
Consists of zero, one, or more statements.
Behaves like a single statement to the outside world..
May be nested (e.g., it may contain one or more other blocks of code inside).
Generally belong to whatever comes before it. Although it is perfectly OK to create a block that does not, this is almost never done.

A complete method is a single block of code, most likely with nested blocks.

The diagram below illustrates how blocks of code can be nested:

If you want, go ahead and modify your Hello World program to match this example.

Comments

A comment:

Is additional, non-executable text in a program used to document code.
May also be used to temporarily disable a section of code (for debugging).

Block Comments

Block comments are preceded by /* and followed by */.

Some rules for block comments:

May not be nested.
May be one or more lines.

May span part of a line, for example, to temporarily disable part of a statement:

Single-line Comments

A single line can be commented by preceding the comment with two forward slashes: //. Note that:

The comment ends at the end of that line.
Single-line comments may be nested inside block comments.

Java specifies a third type of comment, the javadoc comment:

Java contains a self-documentation utility, javadoc, which builds documentation from comments within the code.
javadoc comments begin with /** and end with */.
Comments only work as javadoc comments when placed at specific locations in your code (immediately above anything documentable - the class itself and its members), otherwise they are treated as ordinary comments.

3 - JAVA VARIABLES

Variables store data that your code can use.

There are two fundamental categories of variables, primitive data and references:

With primitive data, the compiler names a memory location and uses itto store the actual data - numeric values such as integers, floating point values, and the code values of single individual text characters are stored as primitives.
With references, the data is accessed indirectly - the compiler selects a memory location, associates it with the variable name, and stores in it a value that is effectively the memory address of the actual data - in Java, all objects and arrays are stored using references.

In the diagram below, the boxes are areas in memory:

Declaring Variables

Variables must be declared before they are used.

A declaration informs the compiler that you wish to:

Create an identifier that will be accepted by the compiler within a section of code (exactly what that section is depends on how and where the variable is declared; that is the concept of scope, which will be addressed later).
Associate that identifier with a specified type of data, and enforce restrictions related to that in the remainder of your code.
Create a memory location for the specified type of data.
Associate the identifier with that memory location.

Java uses many specific data types; each has different properties in terms of size required and handling by the compiler:

The declaration specifies the name and datatype.
Generally the declaration also defines the variable, meaning that it causes the compiler to allocate storage space in memory of the requested type's size.
A declaration may also assign an initial value (to initialize the variable).
Multiple variables of the same type can be declared in a comma-separated list.

Code	Effect
`int a;`	declares the name `a` to exist, and allocates a memory location to hold a 32-bit integer
`int a = 0;`	same as above, and also assigns an initial value of 0
`int a = 0, b, c = 3;`	declares three integer variables and initializes two of them

Note that different languages have different rules regarding variables that have not been initialized:

Some languages just let the value be whatever happened to be in that memory location already (from some previous operation).
Some languages initialize automatically to 0.
Some languages will produce a compiler or runtime error.
Java uses both of the last two: local variables within methods must be initialized before attempting to use their value, while variables that are fields within objects are automatically set to zero.

Advanced Declarations

Local variables, fields, methods, and classes may be given additional modifiers; keywords that determine special characteristics.

Any modifiers must appear first in any declaration, but multiple modifiers may appear in any order.

Keyword	Usage	Comments
`final`	local variables, fields, methods, classes	The name refers to a fixed item that cannot be changed. For a variable, that means that the value cannot be changed. For a method, the method cannot be overridden when extending the class. A `final` field does not, however, have to be initialized immediately; the initial assignment may be done once during an object's construction.
`static`	fields, methods, inner classes	Only for fields and methods of objects. One copy of the element exists regardless of how many instances are created. The element is created when the class is loaded.
`transient`	fields	The value of this element will not be saved with this object when serialization is used (for example, to save a binary object to a file, or send one across a network connection).
`volatile`	fields	The value of this element may change due to outside influences (other threads), so the compiler should not perform any caching optimizations.
`public, protected, private`	fields, methods classes	Specifies the level of access from other classes to this element - covered in depth later.
`abstract`	methods, classes	Specifies that a method is required for a concrete extension of this class, but that the method will not be created at this level of inheritance - the class must be extended to realize the method. For a class, specifies that the class itself may not be instantiated; only an extending class that is not `abstract` may be instantiated (a class must be `abstract` if one or more of it's methods are `abstract`) - covered in depth later
`native`	methods	The method is realized in native code (as opposed to Java code) - there is an external tool in the JDK for mapping functions from a DLL to these methods.
`strictfp`	methods, classes	For a method, it should perform all calculations in strict floating point (some processors have the ability to perform floating point more accurately by storing intermediate results in a larger number of bits than the final result will have; while more accurate, this means that the results might differ across platforms). For a class, this means that all methods are `strictfp`.
`synchronized`	methods, code blocks	No `synchronized` code may be accessed from multiple threads for the same object instance at the same time.

4 - JAVA DATA

Primitive Data Types

The primitive data types store single values at some memory location that the compiler selects and maps to the variable name you declared .
Primitive values are not objects - they do not have fields or methods.
A primitive value is stored at the named location, while an object is accessed using a reference.
An object reference variable does not store the object's data directly - it stores a reference to the block of data, which is somewhere else in memory (technically, the reference stores the memory address of the object, but you never get to see or use the address).

Primitives Data Types

**Primitives Data Types**
Primitive Type	Storage Size	Comments
`boolean`	`1 bit`	not usable mathematically, but can be used with logical and bitwise operators
`char`	`16 bits`	unsigned, not usable for math without converting to `int`
`byte`	`8 bits`	signed
`short`	`16 bits`	signed
`int`	`32 bits`	signed
`long`	`64 bits`	signed
`float`	`32 bits`	signed
`double`	`64 bits`	signed
`void`	`None`	not really a primitive, but worth including here

Object Data Types

Objects can be data, which can be stored in variables, passed to methods, or returned from methods.

References

As we will see later, objects are stored differently than primitives. An object variable stores a reference to the object (the object is located at some other memory location, and the reference is something like a memory address).

Text Strings

A sequence of text, such as a name, an error message, etc., is known as a string.

n Java, the String class is used to hold a sequence of text characters.

A String object:

Is accessed through a reference, since it is an object.
Has a number of useful methods, for case-sensitive or case-insensitive comparisons, obtaining substrings, determining the number of characters, converting to upper or lower case, etc.
Is immutable; that is, once created it cannot be changed (but you can make your variable reference a different String object at any time).

Literal Values

A value typed into your code is called a literal value.

The compiler makes certain assumptions about literals:

true and false are literal boolean values.
null is a literal reference to nothing (for objects).
A numeric value with no decimal places becomes an int, unless it is immediately assigned into a variable of a smaller type and falls within the valid range for that type.
A value with decimal places becomes a double.
To store a text character, you can put apostrophes around the character.

Code	Effect
`char e = 'X';`	Creates a 16-bit variable to hold the Unicode value for the uppercase X character.

You can add modifiers to values to instruct the compiler what type of value to create (note that all the modifiers described below can use either uppercase or lowercase letters).

Modifying prefixes enable you to use a different number base:

Prefix	Effect
`0X or 0x`	A base 16 value; the extra digits can be either uppercase or lowercase, as in `char c = 0x1b;`
`0`	A base 8 value, as in `int i = 0765;`

Note: using these prefixes will always result in number that is considered positive (so that 0x7F for a byte would be OK, but 0x80 would not, since the latter would have a value of 128, outside the range of byte).
Also note that a long value would need the L modifier as discussed below.

Modifying suffixes create a value of a different type than the default:

`L or l`	a long value (uses 64 bits of storage), as in `long l = 1234567890123456L;`
`L or l`	Note: An `int` value will always implicitly be promoted to a `long` when required, but the reverse is not true; the above notation is necessary because the literal value is larger than 32 bits
`F or f`	A float value, as in `float f = 3.7F;`

Escape Sequences for Character Values

There are a number of escape sequences that are used for special characters:

Escape Sequence	Resulting Character
`\b`	Backspace
`\f`	Form feed
`\n`	Linefeed character - note that it produces exactly one character, Unicode 10 (\u000A in hex)
`\r`	Carriage return
`\t`	Tab
`\"`	Quote mark
`\'`	Apostrophe
`\\`	Backslash
`\uNNNN`	Unicode value, where N is a base 16 digit from 0 through F; valid values are \u0000 through \uFFFF
`\NNN`	Value expressed in octal; ranging from \000 to \377

The escape sequences can either be used for single characters or within strings of text:

5 - JAVA CONSTANTS AND THE FINAL KEYWORD

Java has a means for defining contants, which are like variables in that they have names, but are not changeable once set.

If a variable is declared as final, it cannot be changed:

Even though the variable's value is not changeable once a value has been established, you are allowed to set a unique value once.

Local variables within methods may be declared as final.

Constants' values may be set in an explicit initialization, in a separate line of code, or, as method parameters passed when the method is called.

Fields within a class may be declared as final.

Contants' values may be set in an explicit initialization, in a separate line of code within an initialization block, or in a constructor.

Fields of a class may be declared as public static final - that way they are available to other classes, but cannot be changed by those other classes. An example is Math.PI.

Classes and methods may also be marked as final. We will cover this later.

Code Sample:

Java-Basics/Demos/FinalValues.java

The class has two final fields, scale and answer. The scale is fixed at 100, while the answer is initialized dynamically, but, once established, the value cannot be changed. Try removing the comment from the line that attempts to set it to 44, and you will see the compiler error message that results.

6 - JAVA MATHEMATICS

Looks and behaves like algebra, using variable names and math symbols:

Basic Rules

What goes on the left of the = sign is called an lvalue. Only things that can accept a value can be an lvalue (usually this means a variable name - you can't have a calculation like a + b in front of the equal sign).
Math symbols are known as operators; they include:

Operator	Purpose (Operation Performed)
`+`	for addition
`-`	for subtraction
`*`	for multiplication
`/`	for division
`%`	for modulus (remainder after division)
`(` and `)`	for enclosing a calculation

Note that integer division results in an integer - any remainder is discarded.

Expressions

An expression is anything that can be evaluated to produce a value. Every expression yields a value.

Examples (note that the first few of these are not complete statements):

Two simple expressions:

An expression that contains another expression inside, the (5/c) part:

A statement is an expression; this one that contains another expression inside - the b + (5/c) part, which itself contains an expression inside it (the 5/c part):

Since an assignment statement (using the = sign) is an expression, it also yields a value (the value stored is considered the result of the expression), which allows things like this:

The value stored in a is the value of the expression b + (5/c).

Since an assignment expression's value is the value that was assigned, the same value is then stored in d.

The order of processing is as follows:

Retrieve the value of b.
Retrieve the 5 stored somewhere in memory by the compiler.
Retrieve the value of c.
perform 5 / c
Add the held value of b to the result of the above step.
Store that value into the memory location for a.
Store that same value into the memory location for d.

Here is a moderately complicated expression; let's say that a, b, and c are all double variables, and that a is 5.0, b is 10.0, and c is 20.0:

1.Since the c + 5 is in parentheses, the compiler creates code to evaluate that first, but to perform the c + 5 operation, both elements must be the same type of data, so the thing the compiler creates is a conversion for the 5 to 5.0 as a double.

2.Then the compiler creates code to evaluate 20.0 + 5.0 (at runtime it would become 25.0), reducing the expression to:

3.Next, the compiler adds code to call the Math.sqrt method to evaluate its result, which will be 5.0, so the expression reduces to:

4.Note that the evaluated result of a method is known as the return value, or value returned. 5.Multiplication gets done before addition, the compiler creates that code next, to reduce the expression to:

6.Then the code will perform the addition, yielding:

7.And finally, the assignment is performed so that 55.0 is stored in d.

As implied by the examples we have seen so far, the order of evaluation of a complex expression is not necessarily from left to right. There is a concept called operator precedence that defines the order of operations.

Operator Precedence

Operator precedence specifies the order of evaluation of an expression.

Every language has a "table of operator precedence" that is fairly long and complex, but most languages follow the same general rules:

Anything in parentheses gets evaluated before what is outside the parentheses.
Multiply or divide get done before add and subtract.

Example:

In the expression a = b + 5/c, the 5/c gets calculated first, then the result is added to b, then the overall result is stored in a.
The equal sign (=) is an operator; where on the table do you think it is located?

The basic rule programmers follow is: when in doubt about the order of precedence, use parentheses.

Try the following program:

Code Sample:

Java-Basics/Demos/ExpressionExample.java

Multiple Assignments

Every expression has a value. For an assignment expression, the value assigned is the expression's overall value. This enables chaining of assignments:

x = y = z + 1; is the same as y = z + 1; x = y;

i = (j = k + 1)/2; is the same as j = k + 1; i = j/2;

Quite often, you may need to calculate a value involved in a test, but also store the value for later use:

You might wonder why not just generate the random number when we declare x? In this case, that would make sense, but in a loop the approach shown above might be easier such that:

generates the random number and stores it in x.
as an expression, that results in the same value, which is then tested for less than 0.5, and the loop body executes if that is true.
the value of x is then available within the block.
after the loop body executes, another random number is generated as the process repeats.

It is usually not necessary to code this way, but you will see it often.

Order of Evaluation

The order of operand evaluation is always left to right, regardless of the precedence of the operators involved.

Code Sample:

Java-Basics/Demos/EvaluationOrder.java

The operands are first evaluated in left to right order, so that the functions are called in the order getA(), then getB(), and, lastly, getC()

But, the returned values are combined together by multiplying the results of getB() and getC(), and then adding the result from getA()

Bitwise Operators

Java has a number of operators for working with the individual bits within a value.

`&`	Bitwise AND, combines individual bits with an AND operation, so that in the resulting value, a bit position is only 1 if that position had a 1 for both operands.
	`int a = 2;`	has the 2 bit set	`0...00000010`
	`int b = 6;`	has the 2 and 4 bits set	`0...00000110`
	`int c = a & b;`	results in 2	`0...00000010`
`\|`	Bitwise OR, combines individual bits with an OR operation, so that in the resulting value, a bit position is 1 if that position had a 1 for either operand.
	`int a = 2;`	has the 2 bit set	`0...00000010`
	`int b = 4;`	has the 4 bit set	`0...00000100`
	`int c = a \| b;`	results in 6	`0...00000110`
`^`	Bitwise exclusive OR (XOR), combines individual bits so that any position that is the same in both operands yields a 0, any bits that differ yield a 1 in that position; this is often used in encryption, since repeating the operation on the result yields the original value again
	`int a = 3;`	has the 1 and 2 bits set	`0...00000011`
	`int b = 6;`	has the 2 and 4 bits set	`0...00000110`
	`int c = a ^ b;`	results in 5	`0...00000101`
	`int d = c ^ b;`	results in 3 again	`0...00000011`
`~`	Bitwise complement. Reverses the state of all bits.
	`int a = 0;`	has no bits set	`0...00000000`
	`int b = ~a;`	has all bits set	`1...11111111`

Bitwise Shift Operators

These operators shift the bits left or right within a 32-bit int value (they do not work with any other type).

`<<`	left shift the bits by the second operand
	`int a = 4;`	has the 4 bit set	`0...00000010`
	`int b = a << 2;`	now has the 16 bit set	`0...00001000`
`>>`	right shift the bits by the second operand with sign-extension (if the first bit is a 1, new bits introduced to fill in on the left come in as 1 bits)
	`int a = -126;`	has all bits except the rightmost set to 1	`10...0000010`
	`int b = a >> 1;`	now has all bits set to 1 (the 0 rolled off the right end, and a 1 was added on the left to match the original leftmost bit; the resulting value is 63)	`110...000001`
`>>>`	right shift the bits by the second operand without sign-extension (bits added on the left always come in as 0)
	`int a = -1;`	has all bits set to 1	`11...1111111`
	`int b = a >>> 31;`	now has all bits set to 0 except the rightmost (all bits except the first rolled off the right end, and 0's were added on the left	`0000000...01`

Compound Operators

Combine multiple effects in one operation: calculation and storage into memory

Operator	Purpose (Operation Performed)
`++`	increment a variable
`--`	decrement a variable; note that `++` and `--` can precede or follow a variable
	if preceding (called prefix), apply the operator and then use the resulting value
	if following (called postfix), retrieve the value of the variable first, use it as the result of the expression, and then apply the operator
`+=`	add an amount to a variable
`-=`	subtract an amount from a variable
`*=`	multiply a variable by an amount
`/=`	divide a variable by an amount
`%=`	set variable equal to remainder after division by an amount
`&=`	perform bitwise AND between left and right, store result into left operand
`\|=`	perform bitwise OR between left and right, store result into left operand
`^=`	perform bitwise XOR between left and right, store result into left operand
`>>=`	shift the variable's bits to the right by an amount with sign-extension
`>>>=`	shift the variable's bits to the right by an amount without sign-extension
`<<=`	shift the variable's bits to the left by an amount

Compound Operator Examples

Statement	Result
`i++;`	increment `i`
`i--;`	decrement `i`
`j = i++;`	retrieve current value of i, hold it as the result of the expression, assign its value to `j`, then increment `i`
`j = ++i;`	increment `i`, then `j = i;`
`x *= 3;`	`x = x * 3;`
`y -= z + 5;`	`y = y - (z + 5);`

It is inevitable that a certification exam will ask a question that requires understanding the steps involved in a postfix increment or decrement: try the following program:

Code Sample:

Java-Basics/Demos/IncrementTest.java

In the first statement, i = i++;, the original value of i (0) is retrieved and held. Then, i is incremented. But, after that, the held value of 0 is put back into i, overwriting the 1!
In the second part, j = i++ + i;, the operands are evaluated from left to right, but each operand is fully evaluated before proceeding to the next. Which means that the increment part of i++ has taken effect before the second appearance of i in the equation, so that the expression reduces to 0 + 1 (recall that the previous operation resulted in i being 0).

Expressions that Mix Data Types: Typecasting

Expressions will often mix different types of data, for example:

The compiler must choose a specific type of data (either integer or floating-point, and the specific size) for each individual expression it evaluates within a statement.

In general, the processor will choose the larger or more complex unit to work with.
In the first case the value 4 will be promoted to a double, which will then be used in the division.
The conversion is done one expression at a time within a statement; so, in the second example, the division will be performed with integer math, resulting in a value of 3, which will then be promoted to a double to finish the statement.

The process of changing the data type of a value is known a typecasting (or casting):

A wideningcast converts a smaller or less precise value into a larger or more precise type - this is done automatically (the compiler does an implicitcast, as above).
A narrowing cast converts a larger or more precise value into a smaller or less precise type (such as from double to int) - this must be coded with an explicit cast.
To code an explicit typecast, put the desired type in parentheses in front of the expression to be converted; for example:

The division will be evaluated as before, meaning the 4 is promoted to a double, and the result is a double, but a double can't be stored in a, so the cast to int is necessary.
Note that casting is an operation, therefore it has a precedence (which is fairly high on the operator precedence table).

The allowable sequence of implicit casts is shown below:

Small Integral Types and Expressions

One aspect of Java that is important to understand is the result of expressions involving the small integral types: byte, char, and short any expression involving these types, other than the compound assignment expressions, is done with int values, so that the result will always be an int.

Try the following (it is the same as the earlier postfix increment example, using byte instead of int):

Note that the increment expression is accepted by the compiler; it is the simple addition in the third line that causes an error.

The Java Language Specification states the promotion rules as follows (note that this concept does not apply to all operators; again, the operators that include assignment do not use it):

When an operator applies binary numeric promotion to a pair of operands, each of which must denote a value of a numeric type, the following rules apply, in order, using widening conversions to convert operands as necessary:

If either operand is of type double, the other is converted to double.
Otherwise, if either operand is of type float, the other is converted to float.
Otherwise, if either operand is of type long, the other is converted to long.
Otherwise, both operands are converted to type int.

7 - JAVA CREATING AND USING METHODS

The method is the basic complete unit of code to perform one task within an object:

In procedural languages, these are called functions, but in OOP they are usually called methods.
Almost all executable code is in some method.
Technically, there is one other place an object-oriented program could have executable code, but that is an advanced topic.
Examples: calculate a trigonometry function like cosine, print data on the screen, read from a file, open a window.
Methods are defined by a name followed by parentheses.
Inputs to the method go inside the parentheses; they are called parameters or arguments to the method.

Using a method in your code, causing it to run, is known as calling the method.

A method call is an expression, so it may result in a value (the method call is evaluated like any other expression).

this value is called the return value, and the method is said to return a value.
the following is an example of a method used as an expression within a larger expression:

Methods must be called with arguments that matching their specified form, known as the function signature:

the signature is the combination of the name of the method with the pattern of its parameters.
the documentation for library-supplied methods will tell you the signature for those methods.
when you call a method, the name of the method and the parameters you pass to it will determine which method will be called, based on the available signatures.
for each argument, Java expects a value - which could be a literal value, a variable, or expression; it must be either the correct type or a value that can be implicitly typecast to the correct type.

All methods in Java must be defined within a class definition. They have complete access to all other elements of the class (fields and other methods, regardless of the access modifier used for that element).

Code Sample:

Java-Basics/Demos/UseMethodsExample.java

This class calls two methods from the Math class: sqrt and sin, both of which expect one parameter which is a double.

When we call sqrt and pass an integer, the compiler converts that to a double to provide the type of data that sqrt expects

Note that even if your program does not call any methods, it has one method that will be called: main(). Things to note:

The definition of main() is that it provides a start point and end point for your program.
Program execution starts with the first statement in main().
If the last statement in main() is executed, the program ends.
The main() does have arguments (any other words typed on the command line).

Creating Methods

There are three things you need to decide for any method:

what it does.
what inputs it needs.
what answer it gives back.

modifiers include the accessibility of this method from outside the class (public, private, protected, or left blank) as well as other possibilities listed earlier in this section.
dataType is a type of data, like int.
methodName is the name of your method.
parameterList is a comma-separated list of parameters; each parameter is listed with its data type first, then its name.
methodBody is the set of statements that perform the task of the method.
return is a keyword that says to use the result expression value as the result of calling the method, and send that value back to the code that called the method (as an expression, a call to a method evaluates to the returned value; i.e., calling Math.sqrt(4) evaluates to the value that sqrt returned).
if a method declares that it returns a value of a certain type, then it must explicitly return a value of that type.

Method Examples

public methods are accessible to any other class.
void is a keyword for a returned data type that means no data at all - this method does not calculate a result.
The name of the method is sayHello.
This method could be called as follows:


				   showNumber(5);	from within the class

x.showNumber(5);	from outside the class, for an instance x of this class

This method does calculate a result; the data type it calculates is int.
This method must be given two parameters, both of which are int data types.
This method could be called as follows:

int value = calculateSum(4, 6);	from within the class

int value = x.calculateSum(4, 6);	from outside the class, for an instance x of this class

Return Values

Note that the listing of a data type word in front of a name is something we have seen before, in declaring variables. The purpose is the same - to state what type of data this element provides when used in an expression.

The first statement below states that the value of a is an int, so that the compiler knows what memory size to allocate and what type of processing to use with it when it evaluates the second statement.

The effect is no different using a method; recall the function signature (the first line) of our calculateSum method:

It states that the result of evaluating calculateSum is an int, so that the compiler knows what memory size to allocate for the result, and what type of processing to use with it when it evaluates a statement like:

When this statement gets processed, the calculateSum method will run and return its result (which will be the value 10 as an int).

Thus the statement in effect is reduced to:

Method Parameters

Method parameters are also declarations. They declare a type of data received by the method, and also provide a name for each value so it can be used within the method.

Back to our method:

The parameter list declares two variables that will exist in this method: num1 and num2.
The order is important - num1 will be the first value given to the method, num2 will be the second.
The difference between method parameter declarations and the variable declarations we saw before is that the method parameters receive their values when the method is called.

8 - JAVA VARIABLES SCOPE

The variable scope rules are similar to those in C++.

Variables can be declared at any point in your code, not just at the top of a block:

Local variables (those within methods) are not visible to any code that precedes the declaration.
Object elements are visible to any code within the object, regardless of the order of declaration.

Variables declared within a set of curly braces cease to exist after the closing brace has been reached (it is said that they go out of scope); therefore, local variables exist only within that method.

Variables can be declared in the control portion of a for loop, and will exist for the duration of the loop

Parameters to a method are local variables within that method

It is legal to use the same variable name in different scopes, as long as the two scopes have no irresolvable conflicts. Some explanation:

Non-overlapping scopes. For example, two different methods could each have a local variable called firstName.
Overlapping scopes. It is valid for a method to have a variable whose name conflicts with a property name for that class - in that case, the local variable hides the property, but there is a special syntax that allows the method to access the property; we will cover this later.
It is legal for a method and a field of a class to have the same name, although it is not considered a good practice to do so.
An example of an irresolvable conflict is declaring a local variable within a block when the same name is already in scope in that method as a local variable.

Code Sample:

Java-Basics/Demos/MethodExample.java

We will cover the concept of static elements later, but, for now, since main is static, the methods it calls must be static as well

9 - JAVA COMPARISONS AND CONTROL STRUCTURES

Boolean-valued Expressions

Java has a data type called boolean. Note the following:

Possible values are true or false.
boolean can be operated on with logical or bitwise operators, but cannot be treated as a 0 or 1 mathematically.
boolean can be specified as a parameter type or return value for a method.
A boolean value will print as true or false.

The result of a conditional expression (such as a comparison operation) is a boolean value. Note that:

Simple comparisons, such as greater than, equal to, etc., are allowed.
Values are returned from functions.
Complex combinations of simpler conditions are allowed.

Conditional expressions are used for program control. That means they provide the ability for a program to branch based on the runtime condition or iterate through a block of code until the condition is false.

Comparison Operators

This chart shows the comparison operators and the types of data they can be applied to.

This chart shows the comparison operators and the types of data they can be applied to.
Operator	Purpose (Operation Performed)	Types of Data
Operator	Purpose (Operation Performed)	`boolean`	Numeric Primitives and `char`	Object References
`==`	is equal to (note the two equals signs!)	X	X	X
`!=`	is not equal to	X	X	X
`>`	is greater than		X
`<`	is less than		X
`>=`	is greater than or equal to		X
`<=`	is less than or equal to		X

Note that it is unwise to use == or != with floating-point data types, as they can be imprecise.

Comparing Objects

The operators == and != test if two references point to exactly the same object in memory – they test that the numeric values of the two references are the same. The equals(Object o) method compares the contents of two objects to see if they are the same (you can override this method for your classes to perform any test you want).

Conditional Expression Examples

The following are conditional expression examples.

a = 3; b = 4;
a == b will evaluate to false
a != b will evaluate to true
a > b will evaluate to false
a < b will evaluate to true
a >= b will evaluate to false
a <= b will evaluate to true

s == t will evaluate to false

s != t will evaluate to true (they are not the same object - they are two different objects that have the same contents)

s.equals(t) will evaluate to true

s == t will evaluate to true

s != t will evaluate to false (they are the same object)

s.equals(t) will evaluate to true

Note: Java will intern a literal String that is used more than once in your code; that is, it will use the same location for all occurrences of that String

s == t will evaluate to true, because the String object storing "Hello" is stored only once, and both s and t reference that location

s != t will evaluate to false (they are the same object)

s.equals(t) will evaluate to true

Complex boolean Expressions

Java has operators for combining boolean values with AND and OR logic, and for negating a value (a NOT operation). Note that:

There are also bitwise operators for AND, OR, and bitwise inversion (changing all 1 bits to 0, and vice versa).
Since a boolean is stored as one bit, the bitwise AND and OR operators will give the same logical result, but will be applied differently (see below).
For some reason, the bitwise NOT cannot be applied to a boolean value.

Logical		Bitwise
`&&`	logical AND	`&`	bitwise AND
`\|\|`	logical OR	`\|`	bitwise OR
`!`	logical NOT	`~`	bitwise NOT (inversion)

Code	Effect
Testing if a value falls within a range
`( ( a >= 0 ) && ( a <= 10 ) )`	is `true` if `a` is falls between 0 and 10; it must satisfy both conditions
Testing if a value falls outside a range
`( ( a < 0 ) \|\| ( a > 10 ) )`	is `true` if `a` falls outside the range 0 to 10; it may be either below or above that range
`( !( ( a >= 0 ) && ( a <= 10) ) )`	inverts the test for `a` between 0 and 10; so `a` must be outside the range instead of inside it

The && and || operations are called short-circuiting, because if the first condition determines the final outcome, the second condition is not evaluated.

To force both conditions to be evaluated, use & and | for AND and OR, respectively.

Example: to test if a reference is null before calling a boolean valued method on it.

equalsIgnoreCase will be called only if the reference is not null.

The if Statement

Causes "one thing" to occur when a specified condition is met.

The one thing may be a single statement or a block of statements in curly braces. The remainder of the code (following the if and the statement or block it owns) is then executed regardless of the result of the condition.

The conditional expression is placed within parentheses.

The following flowchart shows the path of execution:

if Statement Examples

Absolute Value

If we needed the absolute value of a number (a number that would always be positive):

Code Sample:

Java-Control/Demos/If1.java

Random Selection

Task: write a brief program which generates a random number between 0 and 1. Print out that the value is in the low, middle, or high third of that range (Math.random() will produce a double value from 0.0 up to but not including 1.0).

Although it is a bit inefficient, just do three separate tests: (note that Math.random() will produce a number greater than or equal to 0.0 and less than 1.0).

Code Sample:

Java-Control/Demos/If2.java

Game01: A Guessing Game

Duration: 15 to 20 minutes. Write a program called Game that will ask the user to guess a number and compare their guess to a stored integer value between 1 and 100.

Use a field called answer to store the expected answer.
For now, just hard-code the stored value; we will create a random value later (your code will be easier to debug if you know the correct answer).
Create a method called play() that holds the logic for the guessing. Use the KeyboardReader class to ask for a number between 1 and 100, read the result, and tell the user if they are too low, correct, or too high.
Create a main method, have it create a new instance of Game and call play().

Solution:

Solutions/Game01/Game.java

Each of the the three possible cases is tested individually as shown below. All three tests will always be performed. In the next version, we will make the tests mutually exclusive, so that processing stops when one is true. we will use a more efficient approach.

Payroll-Control01: Modified Payroll

Duration: 10 to 15 minutes. We will modify our payroll program to check the pay rate and department values.

The Employee class should protect itself from bad data, so modify setPayRate and setDept to check the incoming data (and ignore it if it is less than 0).
Test your program to see what happens with negative input values.
The code using Employee should avoiding sending it bad data, so also change main in Payroll.java to check for acceptable pay rate and department values (print an error message for any negative entry, then just set that variable to 0 (for lack of anything better that we can do right now. Later we will find a way to ask the user for a new value instead)

Solution:

Solutions/Payroll-Control01/employees/Employee.java

The Employee class should protect itself from bad incoming data, so the setPayRate method simply ignores a value less than 0. A better practice, which we will add later, would be to throw an exception when an illegal value is passed in. Note the benefit of coding the constructors to use the setPayRate method; we do not have to go back and revise their code as well. (setDept has similar changes.)

Solution:

Solutions/Payroll-Control01/Payroll.java

Even though Employee now protects itself from illegal incoming values, it should really be the responsibility of the progmmers for the classes using Employee to avoid sending it bad values. So, the payRate value is tested here as well. While this may seem to decrease efficiency (since, presumably, a non-object-oriented program might be able to avoid testing the value twice in a row), the maintainability aspects of OOP are still considered to outweigh the loss in efficiency.

Two Mutually Exclusive Branches

The if ... else Statement

The if ... else Statement does "one thing" if a condition is true, and a different thing if it is false.

It is never the case that both things are done. The "one thing" may be a single statement or a block of statements in curly braces.

A statement executed in a branch may be any statement, including another if or if ... else statement.

This program tells you that you are a winner on average once out of every four tries.

Code Sample:

Java-Control/Demos/IfElse1.java

Nested if ... else Statements - Comparing a Number of Mutually Exclusive Options

You can nestif ... else statements, so that an if or else clause contains another test. Both the if and the else clause can contain any type of statement, including another if or if ... else.

You can test individual values or ranges of values. Once an if condition is true, the rest of the branches will be skipped. You could also use a sequence of if statements without the else clauses (but this doesn't by itself force the branches to be mutually exclusive).

Here is the low/middle/high example rewritten using if ... else

Code Sample:

Java-Control/Demos/IfElse2.java

Similarly, we do not test the high third at all. The original version worked because there was no chance that more than one message would print; that approach is slightly less efficient because all three tests will always be made. In the if ... else version, comparing stops once a match has been made.

Game02: A Revised Guessing Game

Duration: 10 to 15 minutes.

Revise your number guessing program to use if . . . else logic (you can test for too low and too high, and put the message for correct in the final else branch).
Once you have done that, here is a way to generate a random answer between 1 and 100:

1.At the top:

2.Add a private field for a random number generator:

1.Then, you can initialize the answer field:

the nextInt(int n) method generates a number greater than or equal to 0 and less than n, so r.nextInt(100) would range from 0 through 99; we need to add 1 to raise both ends of the range.

4.You might want to print the expected correct answer to aid debugging.

Note that until we cover looping, there will be no way to truly "play" the game, since we have no way to preserve the value between runs.

Solution:

Solutions/Game02/Game.java

Comparing a Number of Mutually Exclusive options - The switch Statement

The switch Statement

A switch expression (usually a variable) is compared against a number of possible values. It is used when the options are each a single, constant value that is exactly comparable (called a case).

The switch expression must be a byte, char, short, or int. Cases may only be byte, char, short, or int values; in addition, their magnitude must be within the range of the switch expression data type and cannot be used with floating-point datatypes or long and cannot compare an option that is a range of values, unless it can be stated as a list of possible values, each treated as a separate case.

Cases are listed under the switch control statement, within curly braces, using the case keyword. Once a match is found, all executable statements below that point are executed, including those belonging to later cases; this allows stacking of multiple cases that use the same code.

The break; statement is used to jump out of the switch block, thus skipping executable steps that are not desired. The default case keyword catches all cases not matched above - note that the default case does not need to be the last thing in the switch. Note that technically speaking, the cases are labeled lines; the switch jumps to the first label whose value matches the switch expression.

Usage

switch Statement Examples

Code Sample:

Java-Control/Demos/Switch1.java

Three points to note:

Stacking of cases for uppercase and lowercase letters allows both possibilities.
break; statements used to separate code for different cases.
default: clause used to catch all other cases not explicitly handled.

Here is a revised version that moves the default to the top, so that a bad entry is flagged with an error message, but then treated as an 'A' - note that there is no break below the default case.

Code Sample:

Java-Control/Demos/Switch2.java

Another example is taking advantage of the "fall-though" behavior without a break statement.

Code Sample:

Java-Control/Demos/Christmas.java

import util.KeyboardReader;

public class Christmas {
  public static void main(String[] args) {
    int day = KeyboardReader.getPromptedInt("What day of Christmas? ");
    System.out.println(
        "On the " + day + " day of Christmas, my true love gave to me:");
    switch (day) {
      case 12: System.out.println("Twelve drummers drumming,"); 
      case 11: System.out.println("Eleven pipers piping,"); 
      case 10: System.out.println("Ten lords a-leaping,"); 
      case 9: System.out.println("Nine ladies dancing,"); 
      case 8: System.out.println("Eight maids a-milking,"); 
      case 7: System.out.println("Seven swans a-swimming,"); 
      case 6: System.out.println("Six geese a-laying,"); 
      case 5: System.out.println("Five golden rings,"); 
      case 4: System.out.println("Four calling birds,"); 
      case 3: System.out.println("Three French hens,"); 
      case 2: System.out.println("Two turtle doves, and a "); 
      case 1: System.out.println("Partridge in a pear tree!");
    }
  }
}

Game03: Multiple Levels

Duration: 15 to 30 minutes. What if we want to offer gamers multiple levels of difficulty in our game? We could make the random number multiplier a property of the Game class, and set a value into it with a constructor, after asking the user what level they'd like to play.

Add a range field to the Game class (an int).
Add a constuctor that accepts a level parameter; use a char.
Within that constructor, use a switch to process the incoming level:

Uppercase or lowercase B means Beginner, set the range to 10.
I means Intermediate; set the range to 100.
A means Advanced; set the range to 1000.
Any other value results a Beginner game; after all, if they can't answer a simple question correctly, how could we expect them to handle something more advanced.
You could put the default option stacked above the "B" cases, so that you can print an error message and then fall through to the 'B' logic

object's nextInt method (move the logic that creates the Random object and generates the answer to this constructor).
Add a default constructor that calls this new constructor, passing 'I' for intermediate.
The prompt given by the play method should now take the range into account.
In the main method, ask the user for the level and call the new constructor with their response.

Solution:

Solutions/Game03/Game.java

The switch tests for the three letters, stacking cases for uppercase and lowercase values. The default catches all other responses and falls through to the Beginner logic.

Comparing Objects

The operators == and != test if two references point to exactly the same object in memory; they test that the numeric values of the two references are the same.

The equals(Object o) method compares the contents of two objects to see if they are the same (you can override this method for your classes to perform any test you want).

When comparing two objects, the == operator compares the references and not the values of the objects. Similarly, != tests to see if the references point to two different objects (even if they happen to have the same internal values).

The Object class defines an equals(Object) method intended to compare the contents of the objects. The code written in the Object class simply compares the references using ==. This method is overridden for most API classes to do an appropriate comparison. For example, with String objects, the method compares the actual characters up to the end of the string. For classes you create, you would override this method to do whatever comparisons you deem appropriate.

Code Sample:

Java-Control/Demos/Rectangle.java

The equals method compares another object to this object.

This example is necessarily somewhat complicated. It involves a few concepts we haven't covered yet, including inheritance. Because the equals method inherited from Object, it takes a parameter which is an Object, we need to keep that that type for the parameter (technically, we don't need to do it by the rules of Java inheritance, but because other tools in the API are coded to pass an Object to this method). But, that means that someone could call this method and pass in something else, like a String.

So, the first thing we need to do is test that the parameter was actually a Rectangle. If so, we can work with it; if not, there is no way it could be equal, so we return false.

We will cover instanceof later, but, for now, we can assume it does what it implies: test that the object we received was an instance of Rectangle. Even after that test, in order to treat it as a Rectangle, we need to do a typecast to explicitly store it into a Rectangle variable (and again, we will cover object typecasting later). Once we have it in a Rectangle variable, we can check its height and width fields.

In yet another complication, if we write an equals method, we should really write a public int hashcode() method as well, since their meanings are interrelated; two elements that compare as equal should produce the same hashcode.

As an aside, note that private data in one instance of a class is visible to other instances of the same class; it is only otherclasses that cannot see the private elements.

Code Sample:

Java-Control/Demos/ObjectEquivalenceIdentity.java

Since all the important work is done in Rectangle, all we need to do here is instantiate two and compare them using both == and the equals method to see the differing results.

The output should be:

Testing Strings for Equivalence

Example - write a brief program which has a word stored as a string of text. Print a message asking for a word, read it, then test if they are the same or not.

you can preset the message assuming that they are incorrect, then change it if they are correct

Code Sample:

Java-Control/Demos/StringEquals.java

try this, then change equals(t) to equalsIgnoreCase(t)

Conditional Expression

Java uses the same conditional expression as C and C++

This performs a conditional test in an expression, resulting in the first value if the condition is true,or the second if the condition is false

Note: due to operator precedence issues, it is often best to enclose the entire expression in parentheses

Example

Code Sample:

Java-Control/Demos/Conditional.java

Note that the parentheses around the test are not necessary by the operator precedence rules, but may help make the code clearer

The parentheses around the entire conditional expression are necessary; without them, precedence rules would concatenate the boolean result onto the initial string, and then the ? operator would be flagged as an error, since the value to its left would not be a boolean.

while and do . . . while Loops

Again, the loops in Java are pretty much the same as in C - with the exception that the conditional expressions must evaluate to only boolean values

while loops

continues as long as the expression evaluates to true
the condition is evaluated before the start of each pass
it is possible that the body of the loop never executes at all (if the condition is false the first time)

do ... while loops

evaluated after the end of each pass
the body of the loop will always execute at least once, even if the condition is false the first time

for Loops

A for loop uses a counter to progress through a series of values

a value is initialized, tested each time through, and then modified (usually incremented) at the end of each pass, before it is tested again
the for loop does not do anything that cannot be done with a while loop, but it puts everything that controls the looping at the top of the block

for loops can use a variable declared out side of the control portion of the loop or in the control portion. The latter gives the variable block-level scope (existing only for the duration of the loop)

A for loop may use multiple control variables by using the sequence operator, the comma ( , )

Note: if you use a block-scope variable (such as above) for the first counter, the additional ones will be block scope as well, and also will be the same type of data - i.e., the variable k above also exists only for the duration of the block. There is no way to declare two counters of different types at block-level scope.

Note that neither while nor do . . . while loops allow declaring a looping variable with this type of scope. The looping variable must be declared in advance.

ForEach Loops

Java 5 introduced a new type of loop, the for-each loop. When you have an array or collection class instance, you can loop through it using a simplified syntax

The looping variable is not a counter - it will contain each element of the array or collection in turn (the actual value and not an index to it, so its type should be the same as the type of items in the array or collection). You can read the : character as if it is the word "from". We will cover this type of loop in more depth in the Arrays section.

For some reason, the looping variable must be declared within the parentheses controlling the loop - you cannot use a preexisting variable.

Since the looping variable is a local variable, it gets a copy of each value from the array or collection. Therefore you cannot use the ForEach loop to write values back to the array/collection - assigning a new value to the variable in the body of the loop is only overwriting the local copy.

Code Sample:

Java-Control/Demos/Loops1.java

Additional Loop Control: break and continue

Breaking Out of a Loop

The break statement will end a loop early and execution jumps to the first statement following the loop. The following example prints random digits until a random value is less than 0.1.

Code Sample:

Java-Control/Demos/Break.java

This code loops, generating and printing a random number for each iteration. If the number is less than 0.1, we break out before printing it.

Code Sample:

Java-Control/Demos/BreakNot.java

This code avoids the break, by creating and testing the random number in the control part of the loop. As part of the iteration condition, if the number is less than 0.1, the loop simply ends "normally".

Continuing a Loop

If you need to stop the current iteration of the loop, but continue the looping process, you can use the continue statement. Note that:

It is normally based on a condition of some sort.
Execution skips to the end of this pass, but continues looping.
It is usually a better practice to reverse the logic of the condition, and place the remainder of the loop under control of the if statement.

Example - a program to enter 10 non-negative numbers

Code Sample:

Java-Control/Demos/Continuer.java

A better way to handle the loop is shown in the commented out version of main - try removing the comment and comment out the original method.

But,continue is easier to use in nested loops, because you can label the level that will be continued

break and continue in Nested Loops

In normal usage, break and continue only affect the current loop; a break in a nested loop would break out of the inner loop, not the outer one

But, you can label a loop, and break or continue at that level. A label is a unique identifier followed by a colon character.

Try the following example as is, then reverse the commenting on the break lines

Code Sample:

Java-Control/Demos/BreakOuter.java

Game04: Guessing Game with a Loop

Duration: 10 to 20 minutes.
(Optional)

Revise the number guessing program to force the user to guess until they are correct (loop-wise, to keep guessing as long as they are incorrect).
Then add more logic to ask if they want to play again, read a Y or N as their answer, and loop as long as they enter a Y.

Solution:

Solutions/Game04/Game.java

Payroll-Control02: Payroll With a Loop

Duration: 20 to 40 minutes.

Revise your payroll program to use only one Employee variable.
Use a loop to repeatedly create a new instance to store in it, populate it from the keyboard, and display it on the screen (you can ask after each one if the user wants to enter another, or just use a loop that has a fixed number of iterations).
Also, change the logic for reading the pay rate and department values from the keyboard to use do . . . while loops that will continue to loop as long as the user enters invalid values (note that you will need to separate declaring the variables from populating them - declare each of them before their loop starts, in order for the variable to be available to the test at the end of the loop).

Solution:

Solutions/Payroll-Control02/Payroll.java

Classpath, Code Libraries, and Jar Files

By now, you may have noticed that every demo and solution folder contains its own copy of util and KeyboardReader. Not only is it inefficient, but it means that we would have to locate and update each copy if we wanted to change KeyboardReader.

A better solution would be to have one master copy somewhere that all of our exercises could access.

Using CLASSPATH
Java has a CLASSPATH concept that enables you to specify multiple locations for .class files, at both compile-time and runtime.

By default, Java uses rt.jar in the current Java installation's jre/lib directory, and assumes that the classpath is the current directory (the working directory in an IDE).
If you create a classpath, the default one disappears, so any classpath that you create must include the current directory using a period (.) character.

To use an external library, you would need to create a classpath in one of two ways:

you can create a system or user environment variable, with multiple directories and/or .jar files, separated by the same delimiter used by your PATH (a semicolon in Windows).
You could use the -classpath option in java and javac (-cp is a shorthand version of that).

Here is an example of a pair of commands to compile and run using an external library stored in a jar file. Note that we need the jar file at both compile-time and runtime. The -cp option in both commands replaces the system classpath with one specifically for that command.

Many Integrated Development Environments (IDEs) have a means to specify project properties; usually an item like "Build Path" will have options to specify external jar files (as well as choose from various libraries supplied with the environment).

Creating a jar File (a Library)
If you wish to create your own library of useful classes, you can bundle one or more classes and/or directories of classes in a jar file. Yyou can also add other resources such as image files.

A jar file contains files in a zipped directory structure. The root level of the file structure should match the root of the package structure; for example, to put KeyboardReader in a jar file, we would want to start at the directory where util is visible, and jar that

The following command will create a jar file called utilities.jar for all files in the util package (just KeyboardReader, in this case).

The options are create, verbose, and use a list of files supplied at the end of the command.

Creating and Using an External Library

Run the command shown above to create utilities.jar.
Move utilities.jar to the ClassFiles directory in your filesystem.
If you remove the util directory from Payroll-Control02, you will not be able to compile or run Payroll as we have been doing.
But, you should be able to compile and run by specifiying a classpath option as shown in the commands above.
You can also temporarily modify the classpath for the duration of your command prompt window as follows (note that you may need to modify the line below to match your setup):

The destination directory can be a relative path from the current directory, or an absolute path. It must already exist, but any subdirectories necessary for package structures will be created.

Also, if you have existing compiled files in the source directories (like employees/Employee.class), then the compiler won't recompile those classes (and therefore they won't end up in the destination path) unless they are older than the associated .java file. You would need to "clean" the directories by deleting the .class files first.

CLASSPATH=%CLASSPATH%;c:\Java102\ClassFiles\utilities.jar

10 - JAVA ARRAYS

Defining and Declaring Arrays

An array stores a group of data items all of the same type.

An array is an object.

An array variable does not actually store the array - it is a reference variable that points to an array object.
Declaring the array variable does not create an array object instance; it merely creates the reference variable - the array object must be instantiated separately.
Once instantiated, the array object contains a block of memory locations for the individual elements.
If the individual elements are not explicitly initialized, they will be set to zero.
Arrays can be created with a size that is determined dynamically (but once created, the size is fixed).

You can read the [] as the word "array".

To declare a variable for an array of integers:

..which you can read as "int array nums".

To declare a variable for an array of String objects:

...which you can read as "String array names" - the array holds String references.

You may also put the brackets after the variable name (as in C/C++), but that is less clearly related to how Java actually works.

But, that syntax does allow the following, which is legal, but seems like a bad practice.

Instantiating Arrays

Instantiate an array object using new, the data type, and an array size in square brackets

The second line constructs a new array object with 10 integer elements, all initialized to 0, and stores the reference into nums.

You can declare and instantiate all at once:

The elements of the array, String references, are initialized to null.

In the above example, names.length would be 3.
The property is fixed (i.e., it is read-only).

The original ten-element array is no longer referenced by nums, since it now points to the new, larger array.

Initializing Arrays

An array can be initialized when it is created

The notation looks like this:

This automatically creates an array of length 3, because there were 3 items supplied.

This array will have a length of 6.

If a new array is being assigned to an existing variable, you cannot use the shorter variant, you must use the new keyword and the data type:

For arrays of other types of objects:

Working With Arrays

The index is the element number, placed within brackets.
Elements are numbered from 0 to one less than the specified size.

The valid elements are 0, 1, and 2, as in:

You could access array elements in a for loop with:

Or, better programming practice would be to use the length property:

The compiler does not check to ensure that you stay within the bounds of the array, but the JVM does check at runtime - if you try to exceed the bounds of the array, an exception will occur.

Note that a zero-length array is valid:

You might create a zero-length array as the return value from a method typed as returning an array, when there are no items to return (as opposed to returning null).

Code Sample:

Java-Arrays/Demos/Arrays1.java

Array Variables

The array as a whole can be referenced by the array name without the brackets, for example, as a parameter to or return value from a function

Code Sample:

Java-Arrays/Demos/Arrays2.java

The array names is passed to printArray, where it is received as data.

Note also the syntax to access a method directly for an array element: data[i].toUpperCase()

Since an array reference is a variable, it can be made to refer to a different array at some point in time

Copying Arrays

You can use System.arraycopy to copy an array into another.

You might do this to expand an array by creating a larger one and copying the contents of the smaller one into it (but any references to the original array will need to be changed to point to the new array).

The declaration is:

Code Sample:

Java-Arrays/Demos/CopyArray.java

The first arraycopy line copys from nums into the first half of biggerNums. The number of items copied is determined by nums.length

The second arraycopy line again copys from nums, but now into the second half of biggerNums. The starting location for the "paste" is nums.length, since that is where we left off the first time. And the number of items copied is again determined by nums.length

Using the args Array

Note that there has been an array declaration in all of our examples thus far; the array of strings passed to main: args

These are the additional words on the command line.

Copy Hello.java to HelloArgs.java, and modify that to loop through args to print each element (remember to rename the class in the declaration line).
Then run the program with something like java HelloArgs From Me and see what happens.

Solution:

Solutions/Arrays/HelloArgs.java

The for loop iterates through the array; each separate word on the command line becomes one element in the array (note that java HelloArgs is not part of the array).

Game-Arrays01: A Guessing Game with Random Messages

Modify your guessing game program to hold an array of several different String messages, all of which have some form of message for "Correct".
Generate a random number in the range from 0 to the size of the array.
Use this value to select one message to print when they guess correctly.
Continue this approach for "Too Low" and "Too High".

import util.*;
import java.util.*;

public class Game {
	private int answer = 67;
	private static String [] correctMessages = 
			{ "Correct", "Right on!", "Most Excellent!" };
	private static String [] lowMessages = 
			{ "Too low", "Try higher next time" };
	private static String [] highMessages = 
			{ "Too high", "Try lower next time" };
	
	public Game() {
		Random r = new Random();
		answer = r.nextInt(100) + 1;
		System.out.println(answer);
	}
	
	public void play() {
		int guess;
		Random r = new Random();
		do {
			guess = KeyboardReader.getPromptedInt("Enter a number 1 -100: ");
			if (guess < answer) 
				System.out.println(lowMessages[r.nextInt(lowMessages.length);
			else if (guess > answer) 
				System.out.println(highMessages[r.nextInt(highMessages.length);
		} while (guess != answer);
		System.out.println(correctMessages[r.nextInt(correctMessages.length);
	}
	
	public static void main(String[] args) {
		char playAgain = 'Y';
		do {
			new Game().play();
			playAgain = KeyboardReader.getPromptedChar("Play again (y/n)?: ");
		} while (playAgain == 'Y' || playAgain == 'y');				
	}
}

There are three arrays of messages; note that they are not all the same size. The code to handle too high, too low, and correct generates a random number between 0 and the appropriate array's length, by using the Random object's nextInt method, and passing the length of the array.

Arrays of Objects

If an array contains objects, those objects' properties and methods may be accessed.

The notation uses the array variable name, the index in brackets, a dot, and the property or method.

Java-Arrays/Demos/Arrays2.java

Code Sample:

Payroll-Arrays01: An Array of employees

Modify the payroll program to use an array of Employee objects with a size of 3 or more (later we will come up with a more flexible solution that allows for the number of employees to change dynamically).
Use a for loop to populate and display the data.
After the loop is complete, ask the user to enter a last name.
Loop through the array to find the element with the matching last name and display it.

Solution:

Solutions/Payroll-Arrays01/Payroll.java

import employees.*;
import util.*;

public class Payroll {	
	public static void main(String[] args) {
		Employee[] e = new Employee[5];
		String fName = null;
		String lName = null;
		int dept = 0;
		double payRate = 0.0;

for (int i = 0; i < e.length; i++) {
			fName = KeyboardReader.getPromptedString("Enter first name: ");
			lName = KeyboardReader.getPromptedString("Enter last name: ");
			do {
				dept = KeyboardReader.getPromptedInt("Enter department: ");
				if (dept <= 0) System.out.println("Department must be >= 0");
			} while (dept <= 0);
			do {
				payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ");
				if (payRate < 0.0) System.out.println("Salary must be >= 0");
			} while (payRate < 0.0);
			e[i] = new Employee(fName, lName, dept, payRate);
			System.out.println(e[i].getPayInfo());
		}

lName = KeyboardReader.getPromptedString("Enter last name to find: ");
		boolean notFound = true;
		for (int i = 0; i < e.length; i++) {
			if (lName.equalsIgnoreCase(e[i].getLastName())) {
				System.out.println("Found: " + e[i].getPayInfo());
				notFound = false;
				break;
			}
		}
		if (notFound) System.out.println("Not found");
	}
}

The code uses e[i].getPayInfo() to print the pay information for employee i. Element i of the array is one employee reference. It uses the same approach to call e[i].getLastName() for each employee to compare with the requested name.

Enhanced for Loops - the For-Each Loop

The collection of values can be any array or an instance of one of the Java Collections classes (to be discussed later)
The looping variable must be declared in the parentheses that create the loop - you cannot use a preexisting variable as the loop variable
The looping variable will represent each item from the collection or array in turn.

You cannot write into the array using a for-each loop. The looping variable you declare receives a copy of the data in the array, so, if you change its value, you are only changing the local copy.

Multi-Dimensional Arrays

A graphic image that is x pixels across and y pixels vertically.
Weather information modeled in a 3-dimensional space, with measurements for these axes: North/South, East/West, and altitude.

Arrays are objects, and, like other objects, declaring a variable does not instantiate the array - that must be done separately. To instantiate a multidimensional array:

The most significant dimension is listed first; the least significant dimension listed last.

The code below could be used to declare an array to store an image that is 640 pixels across and 480 pixels down - in a graphic the image data is stored sequentially across each row; each row is a 640 pixel block; there are 480 of these blocks in our image:

This code might be used for an image where the data is stored in three layers, each of which is an entire 480 by 640 array:

Multidimensional Arrays in Memory

The array contains elements of that type.
The array itself is a type of data.
So a two-dimensional array written as this:

int[][] nums; ...could be thought of as an array of integer arrays, as if it were written as (note that this is not legal syntax): (int[])[] nums; In Java, a two-dimensional array is actually a single array of array reference variables, each of which points to a single dimensional array. To extend the example above: int[][] nums = new int[3][6]; This is an array of 3 elements, each of which is an array of 6 int elements as shown in the diagram below:

Note that it is possible to replace any of the one-dimensional elements with a different one, or that the second-dimension arrays each have a different length - the following line would replace one of the arrays with another of a different length

Example - Printing a Picture

There is a loop that processes each row (the first, or most significant, dimension of the array, each element of which is an array of characters).
Within that loop, another loop prints each character without ending the line.
Then, when the inner loop is done, a newline is printed.

Code Sample:

Java-Arrays/Demos/ArrayPicture.java

public class ArrayPicture { public static void main(String[] args) { char[][] imgData = new char[][] { { ' ',' ',' ',' ',' ',' ',' ' }, { ' ',' ',' ','0',' ',' ',' ' }, { ' ',' ',' ','|',' ',' ',' ' }, { ' ','0','-','+','-','0',' ' }, { ' ',' ',' ','|',' ',' ',' ' }, { ' ',' ',' ','0',' ',' ',' ' }, { ' ',' ',' ',' ',' ',' ',' ' } }; for (int row = 0; row < imgData.length ; row++ ) { for (int col = 0; col < imgData[row].length; col++ ) { System.out.print(imgData[row][col]); } System.out.println(); } } }

Because multi-dimensional arrays are implemented as arrays of array references, it is possible to partially instantiate an array:

This creates nums as a two-dimensional array (better viewed in this case as an array of array references), and creates an array holding three null references to integer arrays

Typecasting with Arrays of Primitives

It is not possible to typecast an array of one type of primitive to an array of another type of primitive. For example, the following will cause compiler errors if the comment marks are removed:

Code Sample:

Java-Arrays/Demos/ArrayTypecast.java

Neither an implicit or explicit typecast can be performed. With a single int i, the copy of it that is given to d can be expanded to a double. But, with the int[] inums, the value that would be given to dnums is just a copy of the reference to inums, so there is no way that each of the individual elements can be expanded to double.

The next chapter will discuss typecasting from arrays of one type of object to another.

11 - JAVA INHERITANCE

All Java objects use inheritance.
Every Java object can trace back up the inheritance tree to the generic class Object.

Note that traditionally the arrows point from the inheriting class to the base class, and the base class is drawn at the top - in the Unified Modeling Language (UML) the arrows point from a class to another class that it depends upon (and the derived class depends upon the base class for its inherited code).
The parent class/child class terms are not recommended, since parent and child is more commonly used for ownership relationships (like a GUI window is a parent to the components placed in it).
To model real-world hierarchies.
To have a set of pluggable items with the same "look and feel," but different internal workings.
To allow customization of a basic set of features.
When a class has been distributed and enhancements would change the way existing methods work (breaking existing code using the class).
To provide a "common point of maintenance."
You can declare a method with the same signature and write new code for it.
You can declare a field again, but this does not replace the original field; it shadows it (the original field exists, but any use of that name in this class and its descendants refers to the memory location of the newly declared element).

Inheritance Examples

Say you were creating an arcade game, with a number of different types of beings that might appear - wizards, trolls, ogres, princesses (or princes), frogs, etc. All of these entities would have some things in common, such as a name, movement, ability to add/subtract from the player's energy - this could be coded in a base class Entity.

For entities that can be chosen and controlled by a player (as opposed to those that merely appear during the course of the game but can't be chosen as a character) a new class Playable could extend Entity by adding the control features.

Then, each individual type of entity would have its own special characteristics; those that can be played would extend Playable, the rest would simply extend Entity.

you could then create an array that stored Entity objects, and fill it with randomly created objects of the specific classes. For example, your code could generate a random number between 0 and 1; if it is between 0.0 and 0.2, create a Wizard, 0.2 - 0.4 a Prince, etc.

The Java API is a set of classes that make extensive use of inheritance. One of the classes used in the GUI is Window; its family tree looks like this:

Payroll with Inheritance

Our payroll program could make use of inheritance if we had different classes of employees: exempt employees, nonexempt employees, and contract employees

They all share basic characteristics such as getting paid (albeit via different algorithms), withholding, having to accumulate year-to-date numbers for numerous categories.

But they have different handling regarding payment calculations, benefits, dependents, etc.

Exempt employees get a monthly salary, while nonexempt get a wage * hours, contract employees are handled similarly to nonexempt, but cannot have benefits or dependents.

This would leave us with an inheritance scheme as follows:

Note that a scheme with ContractEmployee extending NonexemptEmployee might also be a reasonable approach

Derived Class Objects

You can view a derived class object as having a complete base class object inside it. Let's assume that the Entity class defines the fields name, energy, and position, and methods moveTo() and changeEnergy().

The Playable class adds a field playerID, and the Wizard class adds a spells field (an array of spells they can cast) and a castSpell() method.

Any Wizard object contains all the elements inside its box, include those of the base classes. So, for example, the complete set of properties in a Wizard object is:

name
energy
position
playerID
spells

A Wizard reference to a Wizard object has access to any public elements from any class in the inheritance chain from Object to Wizard. Code inside the Wizard class has access to all elements of the base classes (except those defined as private in the base class - those are present, but not directly accessible).

A more complete description of access levels is coming up.

Note: although it appears that a base class object is physically located inside the derived class instance, it is not actually implemented that way.

Polymorphism

Inheritance and References

If a derived class extends a base class, it is not only considered an instance of the derived class, but an instance of the base class as well. The compiler knows that all the features of the base class were inherited, so they are still there to work in the derived class (keeping in mind that they may have been changed).

This demonstrates what is known as an Is A relationship - a derived class object is A base class instance as well.

It is an example of polymorphism; that one reference can store several different types of objects. For example, in the arcade game example, for any character that is used in the game, an Entity reference variable could be used, so that at runtime, any subclass can be instantiated to store in that variable.

For the player's character, a Playable variable could be used.

When this is done, however, the only elements immediately available through the reference are those know to exist; that is, those elements defined in the reference type object. Note that:

The compiler decides what to allow you to do with the variable based upon the type declared for the variable.
merlin.moveTo() would be legal, since that element is guaranteed to be there.
merlin.castSpell() would not be legal, since the definition of Entity does not include it, even though the actual object does have that capability.
The following example gives a hint as to why this is the case:

There is no way the compiler could determine what type of object would actually be created.
The variables names above, shrek, merlin, and charles, are probably not good choices: presumably we know shrek is an ogre, and always will be, so the type might as well be Ogre (unless, of course, he could transmogrify into something else during the game ...).

Dynamic Method Invocation

When a method is called through a reference, the JVM looks to the actual class of the instance to find the method. If it doesn't find it there, it backs up to the ancestor class (the class this class extended) and looks there (and if it doesn't find it there, it backs up again, potentially all the way to Object).

Sooner or later, it will find the method, since if it wasn't defined somewhere in the chain of inheritance, the compiler would not have allowed the class to compile.

In this manner, what you could consider the most advanced (or most derived) version of the method will run, even if you had a base class reference.

So, for our arcade game, an Entity reference could hold a Wizard, and when the moveTo method is called, the Wizard version of moveTo will run.

An interesting aspect of dynamic method invocation is that it occurs even if the method is called from base class code. If, for example:

The Entity class moveTo method called its own toString method.
The Ogre class didn't override moveTo, but did override toString.
For an Ogre stored in an Entity variable, the moveTo method was called.

The Entity version of moveTo would run, but its call to toString would invoke the toString method from Ogre!

Creating a Derived Class

The syntax for extending a base class to create a new class is:

If you do not extend any class, Java assumes you are extending Object by default

Your new class can use the fields and methods contained in the original class (subject to the note coming up in a few pages about access keywords), add new data fields and methods, or replace fields or methods.

A derived class object may be stored in a base class reference variable without any special treatment. If you then want to store that object in a derived class reference again, you can force that with a typecast.

Java doesn't allow multiple inheritance, where one class inherits from two or more classes. Note that:

It does have a concept called an interface, which defines a set of method names.
A class may implement an interface, defining those methods in addition to whatever other methods are in the class.
This allows for several otherwise unrelated classes to have the same set of method names available, and to be treated as the same type of object for that limited set of methods.

Inheritance Example - A Derived Class

When a derived class is created, an object of the new class will in effect contain all the members of the base and derived classes. In some cases, the accessibility modifiers can limit base class members availability in the derived class, but we will cover that issue later.

The following maps out the relation between the derived class and the base class (note that the diagrams show the apparent memory allocation, in a real implementation the base class memory block is not inside the derived class block).

Class Code	Apparent Memory Allocation
public class MyBase { public int x; public void show() { System.out.println("x =" + x); }
class MyDerived extends MyBase { public int y; public void show() { System.out.println("x = " + x); System.out.println("y = " + y); } }

Class Code

Apparent Memory Allocation

public class MyBase {
public int x;
public void show() {
System.out.println("x =" + x);
}

class MyDerived extends MyBase {
public int y;
public void show() {
System.out.println("x = " + x);
System.out.println("y = " + y);
	}
}

Since everything in MyBase is public, code in the MyDerived class has free access to the x value from the MyBase object inside it, as well as y and show() from itself.

The show() method from MyBase is also available, but only within MyDerived class code (but some work is required to get it, since it is hidden by the show() method added with MyDerived) - code in other classes cannot invoke the MyBase version of show() at all.

Inheritance and Access

When inheritance is used to create a new (derived) class from an existing (base) class, everything in the base class is also in the derived class. It may not be accessible; however, the access in the derived class depends on the access in the base class:

Base class access	Accessibility in derived class
`public`	`public`
`protected`	`protected`
`private`	Inaccessible
Unspecified (package access)	Unspecified (package access)

Note that private elements become inaccessible to the derived class - this does not mean that they disappear, or that that there is no way to affect their values, just that they can't be referenced by name in code within the derived class

Also note that a class can extend a class from a different package

Inheritance and Constructors - the super Keyword

Since a derived class object contains the elements of a base class object, it is reasonable to want to use the base class constructor as part of the process of constructing a derived class object.

Constructors are "not inherited". In a sense, this is a moot point, since they would have a different name in the new class, and can't be called by name under any circumstances, so, for example, when one calls new Integer(int i) they shouldn't expect a constructor named Object(int i) to run.

Within a derived class constructor, however, you can use super( parameterList ) to call a base class constructor. Note that:

t must be done as the first line of a constructor.
Therefore, you can't use both this() and super() in the same constructor function.
If you do not explicitly invoke a form of super-constructor, then super() (the form that takes no parameters) will run.
For the superclass, its constructor will either explicitly or implicitly run a constructor for its superclass.
So, when an instance is created, one constructor will run at every level of the inheritance chain, all the way from Object up to the current class.

Code Sample:

Java-Inheritance/Demos/Inheritance1.java

The diagram below shows the structure of our improved classes:

A MyDerived object has two constructors available, as well as both the getX and getY methods and the show method.
Both MyDerived constructors call the super constructor to handle storage of x.
The show method in the derived class overrides the base class version.
Note that you can tell which class's version of show() is running by the different spacing around the = sign.
x from the base class is not available in the derived class, since it is private in MyBase, so the show method in MyDerived must call getX() to obtain the value.

Derived Class Methods that Override Base Class Methods

As we saw before, you can create a method in the derived class with the same name as a base class method. Note that:

The new method overrides (and hides) the original method.
You can still call the base class method from within the derived class if necessary, by adding the super keyword and a dot in front of the method name.
The base class version of the method is not available to outside code.
You can view the super term as providing a reference to the base class object buried inside the derived class.
You cannot do super.super. to back up two levels.
You cannot change the return type when overriding a method, since this would make polymorphism impossible.
Example: a revised MyDerived using super.show()

Inheritance and Default Base Class Constructors

One base class constructor will always run when instantiating a new derived class object.

If you do not explicitly call a base class constructor, the no-arguments base constructor will be automatically run, without the need to call it as super().
But if you do explicitly call a base class constructor, the no-arguments base constructor will not be automatically run.
The no-arguments (or no-args for short) constructor is often called the default constructor, since it is the one that will run by default (and also because you are given it by default if you write no constructors).

Code Sample:

Java-Inheritance/Demos/Inheritance2.java

Each constructor prints a message so that we can follow the flow of execution. Note that using new Violet() causes Purple() to run, and that new Violet(4) also causes Purple() to run.

For the sake of simplicity, the i field has been made protected, but this is not considered a good practice.

If your base class has constructors, but no no-arguments constructor, then the derived class must call one of the existing constructors with super(args), since there will be no default constructor in the base class.

If the base class has a no-arguments constructor that is private, it will be there, but not be available, since private elements are hidden from the derived class. So, again, you must explicitly call an available form of base class constructor, rather than relying on the default.

Try the above code with the Purple() constructor commented out or marked as private.

The Instantiation Process at Runtime

In general, when an object is instantiated, an object is created for each level of the inheritance hierarchy. Each level is completed before the next level is started, and the following takes place at each level:

The memory block for that level is allocated (for derived classes, this means it is sized for the added elements, since the inherited elements were in the base class memory block.
The entire block is zeroed out.
Explicit initializers for that level run, which may involve executable code, for example: private double d = Math.random();
The constructor for that level runs. Note:

Since the class code has already been loaded, and any more basic code has been completed, any methods in this class or inherited from superclasses are available to be called from the constructor.
Note that if this level's constructor calls a superconstructor, all you are really doing is selecting which form of superconstructor will run at the appropriate time. Timing wise, that superconstructor was run before we got to this point.

When the process has completed, the expression that created the instance evaluates to the address of the block for the last unit in the chain.

Inheritance and static Elements

static methods in a class may not be overridden in a derived class. This is because the static method linkages are not resolved with the same dynamic mechanism that non-static methods use. The linkage is established at compile time.

Example - Factoring Person Out of Employee

Since personnel and probably other people in our overall corporate software suite (contact management, perhaps) would have some basic personal attributes in common, we will pull the first and last name fields into a base class representing a person.

Create a new class, Person, in the employees package (that may not be the best place for it, but for convenience we will put it there).
Cut the first and last name fields and the associated get and set methods out of Employee and paste them here (including getFullName).
Create a constructor for Person that sets the first and last names; it would probably b e a good idea to create a default constructor as well.
Declare Employee to extend Person; change the constructor that accepts the first and last name fields to call a super-constructor to accomplish that task.
Note that if getPayInfo() uses firstName and lastname directly, you will need to revise it to call the get methods for those values - why?
We can test the code using a simplified version of Payroll.

Code Sample:

Java-Inheritance/Demos/employees/Person.java

This class includes the name fields and related set and get methods.

Code Sample:

Java-Inheritance/Demos/employees/Employee.java

Since this class now extends Person, the name-related elements are already present, so we remove them from this code. We took advantage of the Person constructor that accepst first and last names in the corresponding Employee constructor.

Note that since getPayInfo calls getFullName, which is now inherited and publicly accessible, that code did not need to change.

Code Sample:

Java-Inheritance/Demos/Payroll.java

No changes need to be made to Payroll to take advantage of the addition of the inheritance hierarchy that we added. The only changes we made were for the sake of brevity.

To revisit the sequence of events when instantiating an Employee using the constructor that accepts the first and last names, department, and pay rate:

Memory for an Object is allocated.
Any Object initializers would run.
The Object() constructor would run.
Memory for a Person is allocated.
If there were any Person initializers, they would run.
The Person constructor would run, because that was the version selected by the Employee constructor we called.
Memory for an Employee is allocated.
If there were any Employee initializers, they would run.
Any additional steps in the Employee constructor we called would run.

Payroll-Inheritance01: Adding Types of Employees

Duration: 30 to 45 minutes. We wish to improve our payroll system to take account of the three different types of employees we actually have: exempt, nonexempt, and contract employees. Rather than use some sort of identifying code as a property, OOP makes use of inheritance to handle this need, since at runtime a type can be programmatically identified. So we will create three new classes that extend Employee:

ExemptEmployee
NonexemptEmployee
ContractEmployee

In our company, exempt employees get a monthly salary, nonexempt an hourly rate that is multiplied by their hours, as do contract employees. There won't be any real difference between nonexempt and contract employees within their code. Realistically, in a real application, there would be, but, even if there weren't, it would still be a good idea to have separate classes, since the class type itself becomes a bit of information about the object. In the exception class hierarchy, there are many classes that have no internal differences; The multiple classes serve merely to identify the type of problem that occured.

We can inherit much of the logic from Employee, such as the pay rate fields and methods, as well as the name-related elements indirectly gained from Person. But, ContractEmployee and NonexemptEmployee will both add logic related to hours, and all three classes will override the getPayInfo method.

Also, the solution code builds upon the Person base class from the preceding example. You can either copy the Person.java file into your working directory and edit Employee.java to match, or just copy the set of files from the Java-Inheritance/Demos directory into your working directory and use those.

Create three new classes, ExemptEmployee, NonexemptEmployee, and ContractEmployee that extend Employee

One possible approach is to copy the Employee.java file into a new file, ExemptEmployee.java, and modify as appropriate.
Then copy that into NonexemptEmployee.java and edit.
Then copy NonexemptEmployee.java into ContractEmployee.java and make the required changes.

Add an hours field for non-exempt and contract employees, along with the associated get and set methods (note that the payRate field will hold a monthly amount for exempt and an hourly amount for nonexempt and contractors).
Revise the getPayInfo method for each new class.

For all three, it should identify which type of employee it is.
For nonexempt and contract employees, calculate payRate * hours as the numeric value for their pay.

Add constructors as you see fit, making use of calls to the appropriate super-constructors.
There is a special main program already in the Exercises folder, Payroll4Inheritance01.java, that you can use to test your classes.

Solution:

Solutions/Payroll-Inheritance01/employees/ExemptEmployee.java

The primary thing to notice about this file is that it rewrites each constructor with one line to call the equivalent form of super.

Solution:

Solutions/Payroll-Inheritance01/employees/NonexemptEmployee.java

In addition to rewriting the existing constructors, this class adds another that accepts hours, as well as appropriate methods to get and set that value.

Solution:

Solutions/Payroll-Inheritance01/employees/ContractEmployee.java

This class is virtually identical to NonexemptEmployee. Realistically, there would be differences due to benefits, dependents, etc.

Given the similarity between ContractEmployee and NonexemptEmployee, it might be worth refactoring to have a common base class for hourly employees, especially if there were situations where we would want to work with all hourly employees, regardless of type.

Solution:

Exercises/Payroll4Inheritance01.java

import employees.*;
import util.*;

public class Payroll4Inheritance01 {	
	public static void main(String[] args) {

---- C O D E   O M I T T E D ----
		ExemptEmployee ee = null;
		NonexemptEmployee ne = null;
		ContractEmployee ce = null;

fName = KeyboardReader.getPromptedString("Enter first name: ");
		lName = KeyboardReader.getPromptedString("Enter last name: ");
		dept = KeyboardReader.getPromptedInt("Enter department: ");
		do {
			payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ");
			if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
		} while (payRate < 0.0);
		ee = new ExemptEmployee(fName, lName, dept, payRate);
		
		System.out.println(ee.getPayInfo());

fName = KeyboardReader.getPromptedString("Enter first name: ");
		lName = KeyboardReader.getPromptedString("Enter last name: ");
		dept = KeyboardReader.getPromptedInt("Enter department: ");
		do {
			payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ");
			if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
		} while (payRate < 0.0);
		do {
			hours = KeyboardReader.getPromptedDouble("Enter hours: ");
			if (hours < 0.0) System.out.println("Hours must be >= 0");
		} while (hours < 0.0);
		ne = new NonexemptEmployee(fName, lName, dept, payRate, hours);

System.out.println(ne.getPayInfo());

fName = KeyboardReader.getPromptedString("Enter first name: ");
		lName = KeyboardReader.getPromptedString("Enter last name: ");
		dept = KeyboardReader.getPromptedInt("Enter department: ");
		do {
			payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ");
			if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
		} while (payRate < 0.0);
		do {
			hours = KeyboardReader.getPromptedDouble("Enter hours: ");
			if (hours < 0.0) System.out.println("Hours must be >= 0");
		} while (hours < 0.0);
		ce = new ContractEmployee(fName, lName, dept, payRate, hours);
		System.out.println(ce.getPayInfo());

}
}

Typecasting with Object References

Object references can be typecast only along a chain of inheritance. If class MyDerived is derived from MyBase, then a reference to one can be typecast to the other. An upcast converts from a derived type to a base type, and will be done implicitly, because it is guaranteed that everything that could be used in the base is also in the derived class.

A downcast converts from a parent type to a derived type, and must be done explicitly.

even though o came from a String, the compiler only recognizes it as an Object, since that is the type of data the variable is declared to hold.

As a memory aid, if you draw your inheritance diagrams with the parent class on top, then an upcast moves up the page, while a downcast moves down the page.

More on Object Typecasts

The compiler will not check your downcasts, other than to confirm that the cast is at least feasible. For instance, there is no possibility of a typecase between String and Integer, since neither is a base class to the other.

But, the JVM will check at runtime to make sure that the cast will succeed. A downcast could fail at runtime because you might call a method that is not there, so the JVM checks when performing the cast in order to fail as soon as possible, rather than possibly having some additional steps execute between casting and using a method.

Since t was not actually a String, this would fail with a runtime exception during the cast operation. At that point, the runtime engine sees that it cannot make the conversion and fails.

You can use a typecast in the flow of an operation, such as:

((MyBase) rv) casts rv to a MyDerived, for which the getY() method is run.

Note the parentheses enclosing the inline typecast operation; this is because the dot operator is higher precedence than the typecast; without them we would be trying to run rv.getY() and typecast the result (technically, Java does not consider the dot an operator, but a separator , like curly braces, parentheses, and square brackets - the net effect is the same, since separators get applied before operators).

Typecasting, Polymorphism, and Dynamic Method Invocation

The concept of polymorphism means "one thing - many forms."

In this case, the one thing is a base class variable; the many forms are the different types derived from that base class that can be stored in the variable.

Storing a reference in a variable of a base type does not change the contents of the object, just the compiler's identification of its type - it still has its original methods and fields.

You must explicitly downcast the references back to their original class in order to access their unique properties and methods. If you have upcast, to store a derived class object with a base class reference, the compiler will not recognize the existence of derived class methods that were not in the base class.

The collection classes, such as Vector, are defined to store Objects, so that anything you store in them loses its identity. You must downcast the reference back to the derived type in order to access those methods. The introduction of generics in Java 1.5 provides a solution to this annoyance (more on this in the Collections lesson).

During execution, using a base class reference to call to a method that has been overridden in the derived class will result in the derived class version being used. This is called dynamic method invocation.

The following example prints the same way twice, even though two different types of variable are used to reference the object:

Code Sample:

Java-Inheritance/Demos/Inheritance3.java

Situations where you would often see a base class reference:

Parameters to methods that only need to work with base class elements of the incoming object.
As fields of a class where the class code will only work with the base class elements of the object.
Return values from methods where the actual class returned is not important to the user, and you want to hide the actual class from the user - for example, a java.net.Socket object has a public OutputStream getOutputStream () method that returns an instance of a specialized class that will send data across the network connection that the Socket holds; to use this class you only need to know that it is an OutputStream, since there is no way you could use this class without the Socket it is attached to.

More on Overriding

Changing Access Levels on Overridden Methods

You can change the access level of a method when you override it, but only to make it more accessible.

You can't restrict access any more than it was in the base class.
So, for example, you could take a method that was protected in the base class and make it public.
For example, if a method was public in the base class, the derived class may not override it with a method that has protected, private or package access.

This avoids a logical inconsistency:

Since a base class variable can reference a derived class object, the compiler will allow it to access something that was public in the base class.
If the derived class object actually referenced had changed the access level to private, then the element ought to be unavailable.
This logic could be applied to any restriction in access level, not just public to private.

As a more specific example of why this is the case, imagine that ExemptEmployee overrode public String getPayInfo() with private String getPayInfo().

The compiler would allow

Because Employee, the type on the variable e, says that getPayInfo is public.
But, now at runtime, it shouldn't be accessible, since it is supposed to be private in ExemptEmployee.

Redefining Fields

A new field is created that hides the existence of the original field.
Since it actually a new field being created, the access level and even data type may be whatever you want - they do not have to be the same as the original field.
I don't know of any good reason to do this deliberately, but it is possible.

A strange thing happens when you use a base class reference to such a class where the field was accessible (for example, public).
The base class reference sees the base class version of the field!

But, if you were to extend a class from the Java API or other library, you wouldn't necessarily know what fields it had - this facility allows you to use whatever field names you want, and, as long as the base class versions were private, you would not get any adverse effects.

Object Typecasting Example

Say our game program needed to store references to Entity objects.

The exact type of Entity would be unknown at compile time.

But during execution we would like to instantiate different types of Entity at random.

Perhaps our code for Entity includes a method moveTo() that moves it to a new location. Many of the entities move the same way, but perhaps some can fly, etc. We could write a generally useful form of moveTo in the Entity class, but then override it as necessary in some of the classes derived from Entity.

Code Sample:

Java-Inheritance/Demos/EntityTest.java

class Entity {
  private String name;
  public Entity(String name) { this.name = name; }
  public String getName() { return name; }
  public void move() {
    System.out.println("I am " + name + ". Here I go!");
  }
}

class Playable extends Entity {
  public Playable(String name) { super(name); }
  public void move() {
    System.out.println("I am Playable " + getName() + ". Here we go!");
  }
}

class Ogre extends Entity {
  public Ogre(String name) { super(name); }
}

class Troll extends Entity {
  public Troll(String name) { super(name); }
}

class Prince extends Playable {
  public Prince(String name) { super(name); }
  // does not override public void move()
}

class Princess extends Playable {
  public Princess(String name) { super(name); }
  public void move() {
    System.out.println("I am Princess " + getName() + 
        ". Watch as I and my court move!");
  }
}

class Wizard extends Playable {
  public Wizard(String name) { super(name); }
  public void move() {
    System.out.println("I am the Wizard " + getName() + 
        ". Watch me translocate!");
  }
}

public class EntityTest {
  public static void main(String[] args) {
    String[] names = { "Glogg", "Blort", "Gruff", 
                      "Gwendolyne", "Snow White", "Diana",
                      "Merlin", "Houdini", "Charles", "George" };
    for (int i = 0; i < 10; i++) {
      int r = (int) (Math.random() * 5);
      Entity e = null;
      switch (r) {
        case 0: e = new Ogre(names[i]); break;
        case 1: e = new Troll(names[i]); break;
        case 2: e = new Wizard(names[i]); break;
        case 3: e = new Prince(names[i]); break;
        case 4: e = new Princess(names[i]); break;
      }
      e.move();
    }
  }
}

The compiler allows the calls to the moveTo method because it is guaranteed to be present in any of the subclasses - since it was created in the base class.

If not overridden in the derived class, then the base class version will be used.

If the method is overridden by the derived class, then the derived class version will be used.

At runtime, the JVM searches for the method implementation, starting at the actual class of the instance, and moving up the inheritance hierarchy until it finds where the method was implemented, so the most derived version will run.

Checking an Object's Type: Using instanceof

Given that you can have base class references to several different derived class types, you will eventually come to a situation where you need to determine exactly which derived class is referenced - you may not know it at the time the program is compiled.

In the above example, perhaps wizards, ogres, trolls, etc. have their own special methods.

How would you know which method to call if you had an Entity reference that could hold any subclass at any time?

The instanceof operator is used in comparisons - it gives a boolean answer when used to compare an object reference with a class name.

It will yield true if the reference points to an instance of that class.

It will also give true if the object is a derived class of the one tested.

If the test yields true, then you can safely typecast to call a derived class method (you still need to typecast to call the method - the compiler doesn't care that you performed the test).

For example:

There is another method of testing:

Every object has a getClass() method that returns a Class object that uniquely identifies each class.
Every class has a class pseudo-property that provides the same Class object as above; this object is the class as loaded into the JVM (technically, class isn't a field, but syntax-wise it is treated somewhat like a static field).
With this method, a derived class object's class will compare as not equal to the base class.

It is rare that you would need this type of test.

Payroll-Inheritance02: Using the Employee Subclasses

Duration: 45 to 60 minutes.

n the main method of Payroll, reinstate the array of Employee objects.
Create instances of the non-exempt employees, exempt employees, and contract employees to fill the array. You can ask which type of employee using getPromptedChar, then break up the existing sections of code that enter one specific type as in: boolean badType; do { badType = false; char empType = KeyboardReader.getPromptedChar("Enter employee type (E, N, C): "); switch (emptype) { case 'E': case 'e': (existing code to enter one ExemptEmployee, modified to use current array element as the variable) break; case 'N': case 'n': (existing code to enter one NonexemptEmployee, modified to use current array element as the variable) break; case 'C': case 'c': (existing code to enter one ContractEmployee, modified to use current array element as the variable) break; default: badType = true; (Print error message) } } while (badType); You will see a slightly different approach in the solution code, which avoids duplicating the code to read the name and department data.
Create a report that lists all employees, grouped by type, by looping through the array three times.
- The first time, show all exempt employees and their pay information .
- The second time. print only the non-exempt employees and their pay information.
- The third time. print contract employees and their pay information.
- Since you'll be writing the same loop multiple times, you could try both indexed loops and for-each loops (the solution uses for-each loops).

Solution:

Solutions/Payroll-Inheritance02/Payroll.java

import employees.*;
import util.*;

public class Payroll {  
	public static void main(String[] args) {

---- C O D E   O M I T T E D ----
		for (int i = 0; i < e.length; i++) {
			char type = 
				KeyboardReader.getPromptedChar("Enter type: E, N, or C: ");
			if (type != 'e' amp;&& type != 'E' && 
					type != 'n' amp;&& type != 'N' && 
					type != 'c' amp;&& type != 'C') {
				System.out.println("Please enter a valid type");
				i--;
				continue;        
			}
			fName = KeyboardReader.getPromptedString("Enter first name: ");
			lName = KeyboardReader.getPromptedString("Enter last name: ");
			do {
				dept = KeyboardReader.getPromptedInt("Enter department: ");
				if (dept <= 0) System.out.println("Department must be >= 0");
			} while (dept <= 0);
			do {
				payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ");
				if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
			} while (payRate < 0.0);

switch (type) {
				case 'e':
				case 'E': e[i] = new ExemptEmployee(fName, lName, dept, payRate);
									break;
				case 'n':
				case 'N': do {
										hours = 
											KeyboardReader.getPromptedDouble("Enter hours: ");
										if (hours < 0.0) 
											System.out.println("Hours must be >= 0");
									} while (hours < 0.0);
									e[i] = new NonexemptEmployee(fName, lName, dept, 
												payRate, hours);
									break;
				case 'c':
				case 'C': do {
										hours = 
											KeyboardReader.getPromptedDouble("Enter hours: ");
										if (hours < 0.0) 
											System.out.println("Hours must be >= 0");
									} while (hours < 0.0);
									e[i] = new ContractEmployee(fName, lName, dept, 
												payRate, hours);
			}

}

System.out.println();
		System.out.println("Exempt Employees");
		System.out.println("====== =========");
		for (Employee emp : e) {
			if (emp instanceof ExemptEmployee) {
				System.out.println(emp.getPayInfo());
			}
		}
		System.out.println();
		System.out.println("Nonexempt Employees");
		System.out.println("======== =========");
		for (Employee emp : e) {
			if (emp instanceof NonexemptEmployee) {
				System.out.println(emp.getPayInfo());
			}
		}
		System.out.println();
		System.out.println("Contract Employees");
		System.out.println("======== =========");
		for (Employee emp : e) {
			if (emp instanceof ContractEmployee) {
				System.out.println(emp.getPayInfo());
			}
		}
	}
}

We reduced the amount of code by recognizing that some of the data entry logic is common to all three types - asking for first and last names and department before the switch. This required some additional shuffling of declarations, plus some restructuring to avoid asking for the name information all over again if the employee type is not valid (we used continue to avoid processing an employee if the type wasn't valid, and backed up the loop counter to go over the same array location on the next iteration).

For the report, the same logic is essentially repeated three times:

The instanceof test enables us to isolate just one type of employee to print; the others will be skipped over.

Payroll-Inheritance03: Making our base classes abstract

Duration: 5 to 5 minutes.

Mark the Person and Employee classes as abstract
Make the getPayInfo() method abstract in Employee

Solution:

Solutions/Payroll-Inheritance03/employees/Person.java

Solution:

Solutions/Payroll-Inheritance03/employees/Employee.java

package employees; public abstract class Employee extends Person { ---- C O D E O M I T T E D ---- public abstract String getPayInfo(); }

Methods Inherited from Object

There are a number of useful methods defined for Object.

Some are useful as is, such as:

Class getClass() - returns a Class object (a representation of the class that can be used for comparisons or for retrieving information about the class).

Others are useful when overridden with code specific to the new class:

Object clone() - creates a new object that is a copy of the original object. This method must be overridden, otherwise an exception will occur (the Object version of clone throws a CloneNotSupportedException).

The issue is whether to perform a shallow copy or a deep copy - a shallow copy merely copies the same reference addresses, so that both the original object and the new object point to the same internal objects; a deep copy makes copies of all the internal objects (and then what if the internal objects contained references to objects ...? ).

boolean equals(Object) - does a comparison between this object and another. If you don't override this method, you get the same result as if you used == (that is, the two references must point to the same object to compare as equal - two different objects with the same field values would compare as unequal) - that is how the method is written in the Object class. You would override this method with whatever you need to perform a comparison.

int hashCode() - returns an integer value used by collection objects that store elements using a hashtable. Elements that compare as the same using the equals(Object) method should have the same hashcode.

String toString() - converts this object to a string representation.

This method is called by a some elements in the Java API when the object is used in a situation that requires a String, for example, when you concatenate the object with an existing String, or send the object to System.out.println().

Note that the call to toString is not made automatically as a typecast to a String - the only behavior built into the syntax of Java is string concatenation with the + sign (so one of the operands must already be a String); the code in println is explicitly written to call toString.

If you don't override this method, you will get a strange string including the full class name and the hashcode for the object void finalize() - called by the JVM when the object is garbage-collected. This method might never be called (the program may end without the object being collected).

There are also a several methods (wait, notify, and notifyAll) related to locking and unlocking an object in multithreaded situations.

Code Sample:

Java-Inheritance/Demos/ObjectMethods.java

public class ObjectMethods {
  int id;
  String name;
  int age;

ObjectMethods(int id, String name, int age) {
    this.id = id;
    this.name = name;
    this.age = age;
  }
  public boolean equals(Object x) {
    if (x == this) return true;
    else if (x instanceof ObjectMethods) {
      ObjectMethods omx = (ObjectMethods) x;
      return id == omx.id amp;amp;&amp;&amp; name.equals(omx.name) amp;amp;&amp;&amp; age == omx.age;
    }
    else return false;
  }
  public int hashCode() {
    return id + age * 1000;
  }
  public String toString() {
    return id + " " + name + " is " + age + " years old";
  }
  public Object clone() {
    return new ObjectMethods(id, name, age);
  }
  public static void main(String[] args) {
    ObjectMethods om1 = new ObjectMethods (1, "John", 6);
    ObjectMethods om2 = new ObjectMethods (1, "John", 6);
    ObjectMethods om3 = new ObjectMethods (2, "Jane", 5);
    ObjectMethods om4 = (ObjectMethods)om3.clone();
    System.out.println("Printing an object: " + om1);
    if (om1.equals(om2)) 
      System.out.println("om1 equals(om2)");
    if (om1.equals(om3))
      System.out.println("om1 equals(om3)");
    if (om1.equals("John"))
      System.out.println("om1 equals(\"John\")");
    if (om3.equals(om4))
      System.out.println("om3 equals(om4) which was cloned from om3");
    System.out.println("object class is: " + om1.getClass());
  }
}

The clone method returns Object rather than ObjectMethods, since that is how it was declared in the Object class, and you can't change the return type when overriding - thus the typecast on the returned value.

Similarly, the parameter to equals is Object, rather than ObjectMethods. This is not required by Java's syntax rules, but rather a convention that enables other classes to work with this class. For example, the Collections API classes use the equals method to determine if an object is already in a set. If we wrote the method as equals(ObjectMethods om) instead of equals(Object o), the collections classes would call equals(Object o) as inherited from Object, which would test for identity using an == test.

The hashCode method was written out of a sense of duty - Sun specifies that the behavior of hashCode "should be consistent with equals", meaning that if two items compare as equal, then they should have the same hash code - this will be revisited in the section on Collections.

Other Inheritance-related Keywords

abstract

For a class, it states that the class can't be instantiated (it serves merely as a base for inheritance).
For a method, it states that the method is not implemented at this level.
The abstract keyword cannot be used in conjunction with final.

abstract Classes

We will make the Employee class abstract in the next exercise: while the concept of an employee exists, nobody in our payroll system would ever be just an employee , they would be exempt, nonexempt, or contract employees.
While you cannot instantiate an object from an abstract class, you can still create a reference variable whose type is that class.

abstract Methods

The method is not given a body, just a semicolon after the parentheses.
If a class has an abstract method, then the class must also be abstract.
You can extend a class with an abstract method without overriding the method with a concrete implementation, but then the class must be marked as abstract.

final

final Classes

final Methods

final Properties

A final value can be initialized in a constructor or initializer:

The class is final, so it cannot be extended.
in some cases, a declaration of final enables the compiler to optimize methods, since it doesn't have to leave any "hooks" in for potential future inheritance.

12 - JAVA INTERFACES

nterfaces define a standardized set of commands that a class will obey.

The commands are a set of methods that a class implements.

The interface definition states the names of the methods and their return types and argument signatures. There is no executable body for any method that is left to each class that implements the interface.

Once a class implements an interface, the Java compiler knows that an instance of the class will contain the specified set of methods. Therefore, it will allow you to call those methods for an object referenced by a variable whose type is the interface.

Implementing an interface enables a class to be "plugged in" to any situation that requires a specific behavior (manifested through the set of methods).
An analogy: a serial interface on a computer defines a set of pin
/wire assignments and the control signals that will be used. Note that:

The actual devices that can be used may do entirely different tasks: mouse, modem, etc.

But they are all controlled through the same digital instruction mechanism; the individual wires are specified to carry specific signals.

Using an interface rather than inheritance to specify a certain set of methods allows a class to inherit from some other class.

In other words, if a class needs two different sets of methods, so it can behave like two different types of things, it could inherit one set from class A, and use an interface B to specify the other.

You could then reference one of these objects with either an A reference or a B reference.

Interfaces can also specify constants that are public, static, and final.

Creating an Interface Definition

To create an interface definition:

Define it like a Java class, in its own file that matches the interface name.
Use the keyword interface instead of class.
Declare methods using the same approach as abstract methods.

Note the semicolon after each method declaration - and that no executable code is supplied (and no curly braces).
The elements will automatically be public and abstract, and cannot have any other state; it is OK to specify those terms, but not necessary (usually public is specified and abstract is not - that makes it easy to copy the list of methods, paste them into a class, and modify them).

The access level for the entire interface is usually public.

It may be omitted, in which case the interface is only available to other classes in the same package (i.e., in the same directory).
Note, for the sake of completeness, there are situations where the interface definition could be protected or private; these involve what are called inner classes.

Code Sample:

Java-Interfaces/Demos/Printable.java

This interface requires only one method. Any class implementing Printable must contain a public void printall() method in order to compile.

Because the above interface is defined as public, its definition must be in its own file, even though that file will be tiny.

An interface definition may also define fields that are automatically public static final - these are used as constants.

Implementing Interfaces

A class definition may, in addition to whatever else it does, implement one or more interfaces.

Once a class states that it implements an interface, it must supply all the methods defined for that interface, complete with executable code.

Note: it actually does not have to implement all of them, but in that case the class cannot be instantiated - it must be declared as an abstract class that can only be used as a base class (where some derived class would then fully implement the interface).

To implement an interface:

Add that the class implements the interface to the class declaration.

Add the methods specified by the interface to the body of the class. Note that you do need to specify the access terms on methods in a class that implements an interface.

It is important to note that a class may implement an interface in addition to whatever else it might do, so it could have additional fields and methods not associated with the interface.

A class may implement more than one interface - that merely adds to the list of required methods. Use a comma-separated list for the interface names.

Implementing Interfaces - Example

The complete example will use three separate files (the third file will be shown shortly):

Code Sample:

Java-Interfaces/Demos/Printable.java

Code Sample:

Java-Interfaces/Demos/PrintableThings.java

This file contains two classes with package access. Since the classes are not public, they can both be in the same file, and the file name does not need to match either class name. This is done purely as a convenience; it is not a good programming practice in general, but is sometimes useful if one class is highly coupled (interrelated) with the other, which is not the case here. Both classes implement the Printable interface, but are otherwise not related. Stock has another method not related to Printable.

Reference Variables and Interfaces

An interface is like a class where the internal structure and some of the behavior is hidden.

Interfaces are listed like classes in the API documentation.
They compile to a .class file, and get loaded by the same process that loads true classes.
Since a class that implements an interface is a class in all other respects, you can create a reference variable for that class, as usual.
You can also create a reference variable whose type is the interface name.

Only the methods defined in the interface are visible through a variable whose type is the interface.
For a Printable variable containing a Stock instance, the sell method is not visible, since it is not declared in Printable.
Any constants defined by the interface can be accessed without a prefix from code within the class, since implementing the interface makes them part of this class.
To access an interface-implementing class with an interface class reference:

Example:

Both Person and Stock implement Printable.
Therefore, we can create a reference variable to a Printable, and assign either a Person or a Stock object to it.
since the compiler knows that method will exist, no matter which type of object is actually stored in the variable.

Calling an Interface Method

If you have a variable that is declared as a reference to the interface type, you can use it to call an interface method.

Note :that you cannot call any of the additional methods that are not defined by the interface.

Code Sample:

Java-Interfaces/Demos/PrintableTest.java

Once pr has been assigned a Printable instance, we can call pr.printAll();

We cannot directly call the sell() method when pr refers to a Stock, since the compiler would not associate it with a variable whose type was Printable. Note: to compile this, use *.java; since the name of the file containing Stock and Person is PrintableThings.java, the compiler won't be able to find those classes, since it would be looking for Person.java and Stock.java.

Note: you can test the type of object actually contained in an interface reference, and typecast it back to that type.

for instance, to use the sell() method for a Stock:

Interfaces and Inheritance

If a class implements an interface, then all subclasses of it will also automatically implement the interface.

They are guaranteed to have the necessary methods available.

It is a good practice to specify that the derived class implements the interface, just for self-documentation of the code (also for purposes of javadoc, if the base class is not in the same group of files).

An interface definition can inherit from another interface.

The new interface then adds fields and methods to the existing (base) definition.

A class that implements the new interface must implement all methods from the base interface as well as all the additional methods from the new interface definition.

An interface can actually extend multiple base interfaces, in which case the combination of all the methods will be required for any implementing class.

The following interface extends the Printable interface and adds another required method (the new method overloads printAll to print to a specified destination instead of to System.out):

Code Sample:

Java-Interfaces/Demos/Printable2.java

A class implementing Printable2 must define both versions of printAll.

Code Sample:

Java-Interfaces/Demos/Printable2Test.java

Solution:

Solutions/Payroll-Interfaces01/Payroll.java

The last several lines of code create an array of invoices, then use the CheckPrinter to print employees and invoices separately. It would also be possible to create an array of Payable objects, and add in the elements from both the employees and invoices arrays, but that seems like an unneccessary complication for this application.

Exercise: Payroll-Interfaces01

Duration: 30 to 40 minutes. It turns out that our hypothetical system is to be used for all payments our company makes, not just payroll checks, and things like invoices will be paid through the system as well.

Create a finance package, and within it create an interface called Payable.

----it should define the public String getPayInfo() method that our employee classes already implement.

Specify that all the employee classes implement Payable.

The Solutions/Payroll-Interfaces01 directory contains a package called vendors with a class named Invoice - copy this directory to your working directory.

Modify the payroll program by adding an array inv of several invoices (you can just hard-code them).

The Solutions/finance folder also contains a file named CheckPrinter.java - copy that into your finance package. The class has a printChecks(Payable[]) method that you can call twice, once for employees and again for invoices.

Solution:

Solutions/Payroll-Interfaces01/finance/Payable.java

This interface declares the public String getPayInfo() method that our employee classes already implement.

Solution:

Solutions/Payroll-Interfaces01/employees/Employee.java

The class has been marked as implementing Payable. Although it would not be required, we should mark the derived classes the same way, to have more self-documenting code.

Some Uses for Interfaces

Interfaces and Event-Handling

A real-world use of interfaces is for event-handling

An object that can generate an event maintains a list of objects that would like to listen for that event (they will be notified when the event occurs by having one of their methods called).
The object that generates the event fires it by going through its list of objects that want to handle the event, and calling a specified interface method for each object.
A class may handle an event if it implements the interface that is expected for that event - therefore it will have the specified method.
You register an object to handle an event by passing a reference to it to the event-generating object's method that adds a handler.

Assuming that there is an event type called XXXEvent:

The handler interface would probably be named XXXListener.
The method to register a listener would usually be called addXXXListener.
The method generating the event probably has a protected utility method called fireXXXEvent that it uses to trigger the event notifications (and it is available for you to call if you extend the class).

The ActionListener interface is used for GUI events like button clicks.

The event is fired by the GUI object calling the actionPerformed method for any registered listeners (the code to do this is already built into the GUI classes, and the Java API defines the interface shown below).

A class can listen for events if it implements ActionListener.

It can either register itself with the event-generating object, or code outside the class can register it - the example below shows how it would register itself using this:

For the class that fires the event, registering is done with the addActionListener(ActionListener) method, which receives a reference to an ActionListener object:

It adds that reference to a list (maybe a java.util.Vector) of listeners.
When the time comes to fire the event, it walks through the list, calling actionPerformed() for each element on the list (and passing a reference to an event object that it creates).

For the sake of completeness, when the listener interface has multiple methods, there are often abstract classes that implement most or all of the methods as do-nothing methods - so that all you need to do is extend the class and implement the methods that you choose

Interfaces and "Pluggable Components"

The TableModel interface

The Swing classes contain a component called JTable, which displays a spreadsheet-like grid. Note that:

It uses a Model-View-Controller approach to separate these sections of logic into individual classes.
The TableModel interface defines a set of methods that allow a JTable (the controller) to query a data model to find out information in order to display it.
The interface forms a framework for a discussion that will take place between the controller and the model (like, "How many rows do you have?" and, "How many columns?", followed by "What's the value at column 0, row 0?", etc.).

Below are some of the methods from TableModel:

public interface TableModel
int getColumnCount()
Returns the number of columns in the model.
int getRowCount()
Returns the number of rows in the model.
String getColumnName(int columnIndex)
Returns the name of the column at columnIndex.
Class<?> getColumnClass(int columnIndex)
Returns the most specific superclass for all the cell values in the column.
Object getValueAt(int rowIndex, int columnIndex)
Returns the value for the cell at columnIndex and rowIndex.
boolean isCellEditable(int rowIndex, int columnIndex)
Returns true if the cell at rowIndex and columnIndex is editable.
void setValueAt(Object aValue, int rowIndex, int columnIndex)
Sets the value in the cell at columnIndex and rowIndex to aValue.
You can see the conversation that will take place between the controller and the model. Note that:

The controller will ask the model for the number of rows and columns, and, with that information, ask for the value at each location.
It will ask for the type of data with getColumnClass, so it can determine from its settings how to display the values (instances of Number, which Integer, Double, etc., extend, get right-aligned, Boolean columns use a check box, all others get left-aligned - these settings are configurable).
It will get a heading for each column with getColumnName.
If a cell is double-clicked, it can ask if the cell is editable with isCellEditable.

If it is, when the user is done editing, it can put the new data into the model using setValueAt.

Code Sample:

Java-Interfaces/Demos/TableModelExample.java

import java.util.*;
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
import javax.swing.table.*;

public class TableModelExample {

public static void main(String[] args) {

DemoTableModel model = new DemoTableModel();

new TableGUI("Table Model Example", model).setVisible(true);
    new TableConsole(model);
    new TableHTML(model);
  }
}

class DemoTableModel extends AbstractTableModel {

String[] titles = { "Name", "Active", "Grade" };
    String[] names = { "Mary", "Joe", "Sue" };
    Boolean[] actives = { new Boolean(true), new Boolean(false),
                          new Boolean(true) };
    Integer[] grades = { new Integer(99), new Integer(87),
                         new Integer(89) };
    public int getRowCount() { return names.length; }

public int getColumnCount() { return 3; }

public String getColumnName(int col) {
      return titles[col];
    }

public Object getValueAt(int row, int column) {
      if (column == 0) return names[row];
      else if (column == 1) return actives[row];
      else return grades[row];
    }

public void setValueAt(Object v, int row, int column) {}

public Class getColumnClass(int column) {
      if (column == 0) return String.class;
      else if (column == 1) return Boolean.class;
      else return Integer.class;
    }

public boolean isCellEditable(int row, int column) {
      return false;
    }
  }

class TableGUI extends JFrame {

public TableGUI(String title, DemoTableModel model) {
    super(title);
    JTable jt;
    this.setDefaultCloseOperation(EXIT_ON_CLOSE);
    jt = new JTable(model);
    setSize(600,170);
    getContentPane().add(jt);
  }
}

class TableConsole {

TableModel model;

public TableConsole(TableModel model) {

int rows = model.getRowCount();
    int cols = model.getColumnCount();

for (int c = 0; c < cols; c++) {
      System.out.print(fixedStringLength(model.getColumnName(c), 15));
    }
    System.out.println();
    System.out.println("-------------- -------------- -------------- ");
    for (int r = 0; r < rows; r++) {
      for (int c = 0; c < cols; c++) {
        System.out.print(
          fixedStringLength(model.getValueAt(r, c).toString(), 15));
      }
      System.out.println();
    }
  }
  private String fixedStringLength(String in, int size) {
    if (in.length() > size) in = in.substring(0, 15);
    char[] blankArray = new char[size - in.length()];
    for (int i = 0; i < blankArray.length; i++) blankArray[i] = ' ';
    return in + String.valueOf(blankArray);
  }
}

class TableHTML {

TableModel model;

public TableHTML(TableModel model) {
    java.io.PrintStream out = System.out;
    int rows = model.getRowCount();
    int cols = model.getColumnCount();
    out.println("<html><Head><title>My Table</title></head>");
    out.println(
      "<body><table border='1' cellpadding='8' cellspacing='0'><tr>");
    for (int c = 0; c < cols; c++) {
      out.print("<th>" + model.getColumnName(c) + "</th>");
    }
    out.println("</tr>");
    for (int r = 0; r < rows; r++) {
      out.println("<tr>");
      for (int c = 0; c < cols; c++) {
        System.out.print("<td>" + model.getValueAt(r, c) + "</td>");
      }
      out.println("</tr>");
    }
    out.println("</table></body></html>");
  }
}

For convenience, all the classes are in one file.

The DemoTableModel class implements TableModel by extending AbstractTableModel, thus gaining implementations of several methods (like those relating to model change event listener lists), then adding the remaining methods.

The model is based on parallel arrays of student data: name, grade, and active or not- each array represents one column of data, and element 0 in each array is the same student.

The titles array holds column names.

getColumnCount returns 3, because we know that in advance.

getRowCount returns the length of one of the data arrays.

For getColumnName, we return an appropriate string from the titles array.

For getValueAt, we pick an array based on the column number, and return the element at the row index.

getColumnClass returns a class object that matches the type of data for each array.

isCellEditable returns false, and setValueAt does nothing, because our model is not editable.

We then have three possible views of the data: a Swing GUI view that uses a JTable, a console view that prints column-aligned data, and an HTML view that produces HTML code to the console (you can copy that and paste it into a file to view in a browser, like in tablemodel.html).

Since the JTable is the whole reason TableModel exists, it knows what to do with the model. The TableConsole and TableHTML view objects have to explicitly call the appropriate methods in order to display the data.

Marker Interfaces

It is actually possible to have an interface that requires no methods at all! This creates what is called a marker interface.

A declaration that a class implements the interface makes it an instance of that interface, so that it can be passed as a parameter to a method expecting an instance of the interface, or as a return value from a method that declares it returns an instance of the interface.

An example from the API is Serializable

An object that implements Serializable may be turned into a serial data stream, perhaps to save in a file or send across a network connection.
The writeObject method of ObjectOutputStream accepts a parameter whose type is Object, but throws an exception if it doesn't implement Serializable.
The serialization mechanism is recursive, so not only must the object be an instance of Serializable, but any of its object fields must also reference objects that are Serializable (or marked as transient), and any of their fields ... .

Annotations

Java 5 added a new syntax element: the annotation. An annotation is a piece of descriptive data (metadata) about a class, field, or method. It is somewhat like a comment, except that individual annotations are predefined, reusable, and can have effects on either the compilation process or the use of the class once compiled. If you have used an IDE like Eclipse or NetBeans, you may have seen the @Override annotation on editor-supplied template code. This particular annotation tells the compiler that the method that immediately follows is meant to override a base class method (or a method required by an interface). If it does not (because perhaps you spelled the name incorrectly, or got the parameter list wrong), then a compiler error is issued.

Annotations provide Java with a means to achieve, at least to some extent, Aspect-Oriented Programming, or AOP. AOP recognizes cross-cutting concerns, that is, aspects of an element that cut across classes that might not be related by inheritance or implementation of an interface.

An example is a Java web service. While servlets usually extend a Java EE base class (and will always implement the Servlet interface), there is no specified base class or interface for a web service. Instead, configuration information informs the web server that a specific class is intended to be used as a web service, and the server takes steps to make that happen. Prior to annotations, that information was supplied solely by XML configuration files. With Java EE 5, annotations were provided with which a class could be internally marked as a web service.

Annotation Details

Annotations are defined as a sort of interface, but an @ symbol precedes the interface keyword in the declaration (as in @interface). When used, an @ symbol is prepended to the name.
They can be parameterized with optional elements.

A parameter element named value is special - if it is the only element, then it does not need to be named when used (a single value passed to the annotation will be assumed to be the value).
For annotations accepting only one parameter, that parameter should be named value.
An annotation with no parameters serves as a marker, much like implementing the Serializable interface.

They are used as modifiers preceding any target code entities that are declared: class, field, method, constructor, method parameters, return values, package, or local variables.
Based on their specified retention policy, they can be discarded after compilation (the SOURCE policy), or preserved into the compiled class (CLASS persists, but the JVM isn't required to keep the information after the class is loaded, and RUNTIME annotations do remain with the class in the JVM).

@Override is an example of the source type, since it is only needed by the compiler
A runtime type that you might encounter the effect of is @Deprecated, which states that an element is deprecated - you will receive a compiler warning if your code uses an element marked with this annotation (and, since you might be accessing the element in an already-compiled class, this annotation must persist into the compiled class file).
@SuppressWarnings is another source annotation, with an optional element to specify what types of warnings are to be suppressed.

The annotation definitions are themselves annotated: -@Target and @Retention are used before the annotation definition to specify which type of element receives the annotation, and what the retention is.

Using Annotations

To apply an annotation to a class or element, precede the item with the name of the annotation, prefixed with the @ symbol.

If the annotation takes parameters, supply them in parentheses, as a comma separated list of parameterName=parameterValue. If the only parameter is called value, then you can just supply the parameterValue, without specifying it by name.

Code Sample:

Java-Interfaces/Demos/AnnotatedWebService.java

The @WebService annotation persists into compiled code. Tools that work with enterprise-level web servers (like Glassfish, JBoss, etc.), can read the annotation via reflection, and install the class as a web service, performing all the necessary tasks, such as creating a WSDL file, establishing a URL for the service, and installation it under that URL. The annotation can be parameterized with the name for the service (which defaults to the class name followed by "Service"), as well as several other items affecting the setup as a web service.

The serviceName parameter to the @WebService annotation tells the server to set up the service under that name, as opposed to the default, which would have been AnnotatedWebServiceService (the default behavior appends "Service" to the class name, which, in this case, would be redundant).
The @WebMethod annotations tell the server that these methods should be set up as RPC methods which can be remotely invoked (by default, the methods are exposed, the annotation is actually only needed when renaming the method, or to exclude the method from the service, but common practice is to include the unparameterized annotation for methods to be exposed as is).
The @WebParam annotation is used to rename the daysOffset parameter, which would be used from ordinary Java code, to days when the RPC is remotely invoked. Due to the limitations of reflection, where parameter names are not preserved into compiled classes, this annotation is necessary to avoid having the parameters be called arg0, arg1, etc.

13 - JAVA EXEPTIONS

xceptions are generated when a recognized condition, usually an error condition, occurs during the execution of a method. There are a number of standard error conditions defined in Java, and you may define your own error conditions as well.

When an exception is generated, it is said to be thrown.

Java syntax includes a system for managing exceptions, by tracking the potential for each method to throw specific exceptions. Note that:

For each method that could throw an exception, your code must inform the Java compiler that it could throw that specific exception.
The compiler marks that method as potentially throwing that exception, and then requires any code calling the method to handle the possible exception.

There are two ways to handle an exception:

You can try the "risky" code, catch the exception, and do something about it, after which the propagation of the exception ceases.
You can mark the method with the risky statement indcating that it throws an exception. Any statement that calls a method capable of throwing an exception must deal with it.
If the exception occurs in a try block, the JVM looks to the catch block(s) that follow to see if any of them match the exception type.
The first one that matches will be executed.
If none match, then this method ends, and execution jumps to the method that called this one, at the point where the call was made.

Handling Exceptions

Let's say we are writing a method called getThatInt(ResultSet rs) and we want to use the method getInt(int column) from the ResultSet passed in as a parameter:

A look at the API listing for ResultSet tells us that the getInt() method throws SQLException, so we must handle that in our code

1.Use try and catch

2.Declare that the method will throw the exception and let our caller handle it

Note that although you are required to "handle" the exception, you aren't necessarily required to do anything useful about it!

Your decision as to which approach to use should be based on where you think responsibility for handling the exception lies. In the example above, the second approach is probably better, so that the code that works more closely with the SQL handles the exception.

Exception Objects

When an exception is thrown, an exception object is created and passed to the catch block much like a parameter to a method. Note that:

Occurrence of an exception generates an object (an instance of a class in the exception hierarchy) containing information about the exception.

The exception object is passed to the code designated to catch the exception, which may then use methods of the exception object to help handle the situation.

There is an API class called Exception. Note that:

All exception classes inherit from Exception, which inherits from Throwable.

Another class, Error, also inherits from Throwable.

Your code must handle most exceptions, but generally should not attempt to handle Error subtypes (like OutOfMemoryError or StackOverflowError).

RuntimeException is a subclass of Exception that is a base class for all the exception classes that you are not obligated to handle, but still might want to anyway (examples are ArithmeticException, from dividing by zero, NullPointerException, and ArrayIndexOutOfBoundsException).

So, there are several classes of exceptions you are not required to handle (shaded in the image below). Note that:

These extend either Error or RuntimeException.

The ones you are required to handle are called checked exceptions.

Generally, runtime exceptions can be prevented by good coding practices:

Avoid null pointer exceptions by checking the reference first.
Check array indexes before using them to avoid ArrayIndexOutOfBoundsException.
Looking at the documentation for allowable parameter values and testing them before passing them to a method will prevent IllegalArgumentException.

Attempting Risky Code - try and catch

If a method is going to resolve a potential exception internally, the line of code that could generate the exception is placed inside a try block.

There may be other code inside the try block, before and/or after the risky line(s). Any code that depends upon the risky code's success should be in the try block, since it will automatically be skipped if the exception occurs.

There is usually at least one catch block immediately after the try block. A catch block must specify what type of exception it will catch.

There can be more than one catch block, each one marked for a specific exception class.

The exception class that is caught can be any class in the exception hierarchy, either a general (base) class, or a very specific (derived) class.

The catch block(s) must handle all checked exceptions that the try block is known to throw unless you want to throw that exception back to the method that called this one.

It is possible to have a try block without any catch blocks if you have a finally block, but any checked exceptions still need to be caught, or the method needs to declare that it throws them. We will cover finally later in this section.

If an exception occurs within a try block, execution jumps to the first catch block whose exception class matches the exception that occurred (using an instanceof test). Any steps remaining in the try block are skipped. If no exception occurs, then the catch blocks are skipped. The catch blocks will also be skipped if an exception that is not caught occurs, such as a RuntimeException, or an exception that the method declared it throws.

You cannot catch an exception that would not occur in the try block, but you can mark a method as throwing an exception that it doesn't (this leaves open the possibility that an extending class can override the method and actually throw the exception).

Notes on try ... catch Blocks and Variable Scope/Initialization

If you declare a variable within a try block, it will not exist outside the try block, since the curly braces define the scope of the variable. You will often need that variable later, if nowhere else other than the catch or finally blocks, so you would need to declare the variable before the try.

If you declare but don't initialize a variable before a try block, and the only place you set a value for that variable is in the try block, then it is possible when execution leaves the try ... catch structure that the variable never received a value.

So, you would get a "possibly uninitialized value" error message from the compiler, since it actually keeps track of that sort of thing.

Usually this happens with object references; you would generally initialize them to null.

Code Sample:

Java-Exceptions/Demos/ExceptionTest.java

The program will print the first result, then fail while performing the division for the second equation. Execution will jump to the catch block to print our message on the screen.

Note: ArithmeticException is one of the few you are not required to catch, but you can still catch it if you wish.

Example - An Exception You Must Handle

The preceding example used a RuntimeException which your code is not obligated to handle.

Most methods in the I/O classes throw IOException which is an exception you must handle.

Our KeyboardReader class has try and catch to handle this, essentially stifling the exception, since it is unlikely, if not impossible, to actually get an IOException from the keyboard.

Code Sample:

Java-Exceptions/Demos/IOExceptionTest.java

The line marked to comment out throws IOException, but is not in a try block, so the compiler rejects it. The second read attempt is within a try block, as it should be.

Ttry to compile this code as is and then comment out the indicated line.
There is no way we can force an IOException from the keyboard to test the catch block.

Using Multiple catch Blocks

It is possible that a statement might throw more than one kind of exception. You can list a sequence of catch blocks, one for each possible exception. Remember that there is an object hierarchy for exceptions. Since the first one that matches is used and the others skipped, you can put a derived class first and its base class later (you will actually get a compiler error if you list a more basic class before a derived class, as it is "unreachable code").

Code Sample:

Java-Exceptions/Demos/MultiCatchTest.java

The code in the try block could throw NumberFormatException during the parsing, and ArithmeticException while doing the division, so we have catch blocks for those specific cases. The more generic catch block for Exception would catch other problems, like NullPointerException.

Guaranteeing Execution of Code - The finally Block

To guarantee that a line of code runs, whether an exception occurs or not, use a finally block after the try ... catch blocks.

The code in the finally block will almost always execute.

In summary, note the following:

A try block is followed by zero or more catch blocks.

If the catch block exception classes caught are related, the blocks must be listed in inheritance order from most derived to most basic.

There may one finally block as the last block in the structure.
There must be at least one block from the combined set of catch and finally after the try.

It's possible to have a try block followed by a finally block, with no catch block. This is used to prevent an unchecked exception, or an exception the method declared it throws, from exiting the method before cleanup code can be executed.

Code Sample:

Java-Exceptions/Demos/FinallyTest.java

import util.KeyboardReader; public class FinallyTest { public static void main(String[] args) { System.out.println("Returned value is " + go()); } public static int go() { int choice = 0; try { String name = KeyboardReader.getPromptedString("Enter your name: "); System.out.println("MENU:"); System.out.println("1 - normal execution"); System.out.println("2 - uncaught ArithmeticException"); System.out.println("3 - return from try block"); System.out.println("4 - call System.exit"); System.out.println( "5 - return 5 from finally after ArithmeticException"); System.out.println( "6 - return 6 from finally after try returns -1"); System.out.println("X - catch NumberFormatException"); choice = KeyboardReader.getPromptedInt("Enter your choice: "); if (choice == 1) System.out.println("Hello " + name); else if (choice == 2) System.out.println("1 / 0 = " + 1/0); else if (choice == 3) return 3; else if (choice == 4) System.exit(1); else if (choice == 5) System.out.println("1 / 0 = " + 1/0); else if (choice == 6) return -1; } catch (NumberFormatException e) { System.out.println("Number Format Exception occurred"); } finally { System.out.println("Goodbye from finally block"); if (choice == 5) return 5; if (choice == 6) return 6; } return 0; } }

The program shows a menu of possible execution paths you can trigger. The "Goodbye from finally block " message will always appear except from an explicit call to System.exit in the try block:

When no exception occurs, the finally block will execute after the try.
If an uncaught exceptions occurs, like when we divide by zero, the finally block will execute before we are thrown out of the method.
If we execute a return from the try block, the finally block still executes before we leave.
Catching a NumberFormatException is still followed by executing the finally block.
But, calling System.exit in the try block causes the JVM to shut down without executing the finally block.
When we force an uncaught exception but return from the finally block, we do not get a stack trace, indicating that the ArithmeticException just disappeared (compare choices 2 and 5).
When both the try block and the finally block execute a return statement, the value from the finally block is the one actually returned.

Letting an Exception be Thrown to the Method Caller

A method that generates an exception can be written to not catch it. Instead it can let it be thrown back to the method that called it.

The possibility that a method may throw an exception must be defined with the method.

Then an instance of ExceptionClassName or a class that extends it may be thrown so, stating that a method throws Exception is about as generic as you can get (stating that it throws Throwableis as generic as you can get, but not recommended). A method can throw more than one type of exception; in which case you would use a comma-separated list of exception types.

In this way, the method is now marked as throwing that type of exception, and a code that calls this method will be obligated to handle it.

When you extend a class and override a method, you cannot add exceptions to the throws list, but a base class method can list exceptions that it does not throw in the expectation that an overriding method will throw the exception. This is another example of the "inheritance cannot restrict access" principle we saw earlier.

If main() throws an exception, the JVM, which runs under Java rules, will handle the exception (by printing a stack trace and closing down the offending thread. In a single-threaded program, this will shut down the JVM).

Throwing an Exception

The keyword throw is used to trigger the exception-handling process (or, "raise" the exception, as it is often termed in other languages).

That word is followed by an instance of a throwable object, i.e., an instance of a class that extends Throwable. Usually, a new instance of an appropriate exception class is created to contain information about the exception.

For example, suppose a setAge() method expects a nonnegative integer; we can have it throw an IllegalArgumentException if it receives a negative value. It makes sense for the method that calls setAge() to do something about the problem, since it is where the illegal number came from.

So, we can declare setAge() as throws IllegalArgumentException.

Payroll-Exceptions01: Handling NumberFormatException in Payroll

Duration: 5 to 10 minutes. Our program to this point has been prone to potential bad numeric inputs when reading from the keyboard. The parsing methods all throw NumberFormatException.
We could now put each line that requests a number inside a small loop.

The loop could be controlled by a boolean variable, perhaps with a name like isInvalid and initially set to true (using the reverse approach is also a possible strategy).

Inside the loop, we try the read and parse operations.
Then, still in the try block, change the state of the boolean to one that will end the loop (because we wouldn't get to that step unless we succeeded).
In the catch block, print an error message and request to try again.

Where would you put this code? In the payroll main method or in the KeyboardReader class?

Solution:

As a general principle, tools shouldn't attempt to handle exceptions when the handling logic would vary depending on the code using the tool. But, it would be a tremendous burden to put each step of a program that requests a numeric input in a looped try/catch block.

Instead, we could recognize that a common approach would be to loop until the input is numeric, printing an error message each time.

We could overload the get methods in KeyboardReader to accept an error message string, so it could do the looping for us. This way a reasonable solution would be provided, but the original method would still be available if the programmer wants to customize the exception handling.

If a programmer wants a different approach, they are still free to write it in their code and use the original KeyboardReader methods .

Payroll-Exceptions01, continued

Go ahead and add a second version of each get numeric method in KeyboardReader that accepts an error message string as a second parameter; have it loop on each numeric input request until it succeeds without throwing the exception (and printing the error message each time the exception occurs).
Then modify Payroll to call these methods.

Challenge

This approach still doesn't solve the problem of limited employee types, valid department numbers, etc. Can you think of an approach that would? (Hint: interfaces are a powerful tool ...).

Solution:

Solutions/Payroll-Exceptions01/util/KeyboardReader.java

Solution:

Solutions/Payroll-Exceptions01/Payroll.java

import employees.*;
import vendors.*;
import finance.*;
import util.*;

public class Payroll {  
  public static void main(String[] args) {
    Employee[] e = new Employee[5];
    String fName = null;
    String lName = null;
    int dept = 0;
    double payRate = 0.0;
    double hours = 0.0;

for (int i = 0; i < e.length; i++) {
      char type = KeyboardReader.getPromptedChar(
          "Enter type: E, N, or C: ");
      if (type != 'e' && type != 'E' && 
          type != 'n' && type != 'N' && 
          type != 'c' && type != 'C') {
        System.out.println("Please enter a valid type");
        i--;
        continue;        
      }
      fName = KeyboardReader.getPromptedString("Enter first name: ");
      lName = KeyboardReader.getPromptedString("Enter last name: ");
      dept = KeyboardReader.getPromptedInt(
          "Enter department: ", "Department must be numeric");
      do {
        payRate = KeyboardReader.getPromptedDouble(
            "Enter pay rate: ", "Pay rate must be numeric");
        if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
      } while (payRate < 0.0);

switch (type) {
        case 'e':
        case 'E': e[i] = new ExemptEmployee(fName, lName, dept, payRate);
                  break;
        case 'n':
        case 'N': do {
                    hours = KeyboardReader.getPromptedDouble(
                        "Enter hours: ", "Hours must be numeric");
                    if (hours < 0.0) 
                      System.out.println("Hours must be >= 0");
                  } while (hours < 0.0);
                  e[i] = new NonexemptEmployee(
                      fName, lName, dept, payRate, hours);
                  break;
        case 'c':
        case 'C': do {
                    hours = KeyboardReader.getPromptedDouble(
                        "Enter hours: ", "Hours must be numeric");
                    if (hours < 0.0) 
                      System.out.println("Hours must be >= 0");
                  } while (hours < 0.0);
                  e[i] = new ContractEmployee(
                      fName, lName, dept, payRate, hours);
      }

System.out.println(e[i].getPayInfo());
    }

---- C O D E   O M I T T E D ----
  }

}

The revised code uses the new overloads of the getPromptedXXX methods.

Challenge Solution:

Solutions/Payroll-Exceptions01-challenge/util/IntValidator.java

This interface specifies a method that will be used to validate integers. A validator for a specific field (like department) would implement this with code to test for legal values for that field. The package contains similar interfaces for floats and doubles.

Challenge Solution:

Solutions/Payroll-Exceptions01-challenge/employees/DeptValidator.java

This class validates department numbers to be from 1 - 5 inclusive. We also could create separate validators for pay rates, etc.

Challenge Solution:

Solutions/Payroll-Exceptions01-challenge/util/KeyboardReader.java

package util;
import java.io.*;

public class KeyboardReader {

---- C O D E   O M I T T E D ----
	public static int getPromptedInt(String prompt) {
		return Integer.parseInt(getPromptedString(prompt));
	}
	
	public static int getPromptedInt(String prompt, String errMsg) {
		for ( ; ; ) {
			try {
				return Integer.parseInt(getPromptedString(prompt));
			} catch (NumberFormatException e) {
				System.out.println(errMsg);
			}
		}
	}
	public static int getPromptedInt(
			String prompt, String formatErrMsg, 
			IntValidator val, String valErrMsg) {
		for ( ; ; ) {
			try {
				int num = Integer.parseInt(getPromptedString(prompt));
				if (val.accept(num)) return num;
				else System.out.println(valErrMsg);
			} catch (NumberFormatException e) {
				System.out.println(formatErrMsg);
			}
		}
	}
	
	public static float getPromptedFloat(String prompt) {
		return Float.parseFloat(getPromptedString(prompt));
	}
	public static float getPromptedFloat(String prompt, String errMsg) {
		for ( ; ; ) {
			try {
				return Float.parseFloat(getPromptedString(prompt));
			} catch (NumberFormatException e) {
				System.out.println(errMsg);
			}
		}
	}
	public static float getPromptedFloat(
			String prompt, String formatErrMsg, 
			FloatValidator val, String valErrMsg) {
		for ( ; ; ) {
			try {
				float num = Float.parseFloat(getPromptedString(prompt));
				if (val.accept(num)) return num;
				else System.out.println(valErrMsg);
			} catch (NumberFormatException e) {
				System.out.println(formatErrMsg);
			}
		}
	}

public static double getPromptedDouble(String prompt) {
		return Double.parseDouble(getPromptedString(prompt));
	}
	public static double getPromptedDouble(String prompt, String errMsg) {
		for ( ; ; ) {
			try {
				return Double.parseDouble(getPromptedString(prompt));
			} catch (NumberFormatException e) {
				System.out.println(errMsg);
			}
		}
	}
	public static double getPromptedDouble(
			String prompt, String formatErrMsg, 
			DoubleValidator val, String valErrMsg) {
		for ( ; ; ) {
			try {
				double num = Double.parseDouble(getPromptedString(prompt));
				if (val.accept(num)) return num;
				else System.out.println(valErrMsg);
			} catch (NumberFormatException e) {
				System.out.println(formatErrMsg);
			}
		}
	}
}

Exceptions and Inheritance

If a base class method throws an exception, that behavior will also occur in any derived classes that do not override the method.

An overriding method may throw the same exception(s) that the base class method threw.
An overriding method cannot add new exceptions to the throws list. Similar to placing more strict access on the method, this would restrict the derived class object in ways that a base class reference would be unaware of.

If the derived class method does not throw the exception that the base class threw, it can either:

Retain the exception in the throws list, even though it does not throw it; this would enable subclasses to throw the exception.
Remove the exception from its throws list, thus blocking subsequent extensions from throwing that exception.
If you have a base class method that does not throw an exception, but you expect that subclasses might, you can declare the base class to throw that exception.

Exception Class Constructors and Methods

There are several forms of constructors defined in the base class for the exception hierarchy.

Constructor	Description
`Throwable()`	Constructs a new throwable with `null` as its detail message.
`Throwable(String message)`	Constructs a new throwable with the specified detail message.
`Throwable(String message, Throwable cause)`	Constructs a new throwable with the specified detail message and cause.
`Throwable(Throwable cause)`	Constructs a new throwable with the specified cause and a detail message of `(cause==null ? null : cause.toString())` (which typically contains the class and detail message of cause).

The forms involving a cause are used in situations like Servlets and Java Server Pages, where a specific exception is thrown by the JSP engine, but it may be rooted in an exception from your code.

In both cases, a method in a base class is overridden by your code since the writers of the base class did not know what specific exceptions your code might throw, and didn't want to specify something too broad like throws Exception, they settled on throws IOException, ServletException (or JSPException for Java Server Pages).
You would try and catch for your expected exceptions and repackage them inside ServletException objects if you did not want to handle them

Method	Description
`getMessage()`	Prints the message that was associated with the exception (many of the exceptions that deal with outside resources pass on the message from the outside) - for example, when you connect to a database and run a query, that could generate an error in the database; `getMessage()` will show that message.
`printStackTrace()`	Prints to the standard error stream the trace of what function called what function, etc., leading up to the exception. There are variations of this method where you may specify a destination for the printing (note that stack trace includes the message).
`printStackTrace(PrintStream stream)`	Same as above, but prints to the specified output stream (which could be hooked to a log file, for example).

Also worth noting is that the Java Logging API has logging methods that will accept a Throwable parameter and make a log entry with the stack trace.

Creating and Using Your Own Exception Classes

You can create your own exception class by extending an existing exception class.

You could then add any fields or methods that you wish, although often that is not necessary.

You must, however, override any constructors you wish to use: Exception(), Exception(String message), Exception(String message, Throwable cause), Exception(Throwable cause). Usually you can just call the corresponding super-constructor.

If you extend RuntimeException or one of its subclasses, your exception will be treated as a runtime exception (it will not be checked).

When a situation arises for which you would want to throw the exception, use the throw keyword with a new object from your exception class, for example:

Code Sample:

Java-Exceptions/Demos/NewExceptionTest.java

The thrower method randomly throws a NewException, by creating and throwing a new instance of NewException.

main tries to call thrower, and catches the NewException when it occurs.

Payroll-Exceptions02

Duration: 20 to 30 minutes.
Our payroll program can now handle things like a bad numeric input for pay rate (valid format, but not sensible, like a negative number) in a more comprehensive manner. We already are checking the numeric inputs from the keyboard, but there is no guarantee that later code will remember to do this. Using an exception mechanism guarantees protection from invalid values.

In the util package, create an exception class for InvalidValueException. Note that the Java API already contains a class for this purpose, IllegalArgumentException, but it is a RuntimeException - we would like ours to be a checked exception.
In Employee (and potentially its subclasses), change the constructors that accept pay rate and the setPayRate methods to now throw that exception (a question to ask yourself - is it necessary to actually test the pay rate value anywhere other than in the Employee class setPayRate method?). You will see that the effect of throwing the exception ripples through a lot of code. For any code that calls those constructors/methods, choose an appropriate approach to dealing with the potential exception.
The solution uses the validators from the previous challenge exercise, it will work without that feature, but feel free to add that logic into your code as well.

Solution:

Solutions/Payroll-Exceptions02/util/InvalidValueException.java

Solution:

Solutions/Payroll-Exceptions02/employees/Employee.java

The marking of setPayRate throws InvalidValueException ripples through the constructors, so they should be marked as well.

Solution:

Solutions/Payroll-Exceptions02/employees/ExemptEmployee.java

Calling super-constructors that throw our exception requires that these constructors also be marked. The other classes, not shown, should be similarly marked.

Solution:

Solutions/Payroll-Exceptions02/Payroll.java

import employees.*;
import vendors.*;
import util.*;
import finance.*;

public class Payroll {	
	public static void main(String[] args) {

---- C O D E   O M I T T E D ----

for (int i = 0; i < e.length; i++) {
			try {

---- C O D E   O M I T T E D ----

do {
					payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ", 
									"Pay rate must be numeric");
					if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
				} while (payRate < 0.0);
	
				switch (type) {
					case 'e':
					case 'E': e[i] = new ExemptEmployee(fName, lName, dept, payRate);
										break;
					case 'n':
					case 'N': do {
											hours = KeyboardReader.getPromptedDouble(
														"Enter hours: ", "Hours must be numeric");
											if (hours < 0.0) 
												System.out.println("Hours must be >= 0");
										} while (hours < 0.0);
										e[i] = new NonexemptEmployee(fName, lName, dept, 
													payRate, hours);
										break;
					case 'c':
					case 'C': do {
											hours = KeyboardReader.getPromptedDouble(
														"Enter hours: ", "Hours must be numeric");
											if (hours < 0.0) 
												System.out.println("Hours must be >= 0");
										} while (hours < 0.0);
										e[i] = new ContractEmployee(fName, lName, dept, 
													payRate, hours);
				}

---- C O D E   O M I T T E D ----

} catch (InvalidValueException ex) {
					System.out.println(ex.getMessage());
					i--;	//failed, so back up counter to repeat this employee
				}
		}

---- C O D E   O M I T T E D ----

}
}

Since we are already checking the values of the pay rate and hours, we shouldn't expect to see any exceptions thrown, so it is reasonable to put the entire block that gets the employee data and creates an employee in a try block. If we decrement the counter upon a failure, then that employee's data will be requested again.

You might want to test your logic by temporarily changing one of the test conditions you use when reading input (like hours > 0 to hours > -20), so that you can the result (keep count of how many employees you are asked to enter).

Rethrowing Exceptions

An exception may be rethrown.

When we throw an exception, it does not necessarily have to be a new object. We can reuse an existing one.

This allows us to partially process the exception and then pass it up to the method that called this one to complete processing. This is often used in servlets and JSPs to handle part of the problem (possibly just log it), but then pass the problem up to the servlet or JSP container to abort and send an error page.

The stack trace will still have the original information. The fillInStackTrace method for the exception object will replace the original information with information detailing the line on which fillInStackTrace was called as the origin of the exception.

Initializer Blocks

Class properties that are object types can be initialized with a newly constructed object.

The MegaString class constructor code will run whenever a MyClass object is instantiated.

But what if the object's constructor throws an exception?

The MyClass code won't compile - you cannot put a property declaration into a try ... catch structure and there is no place to state that the property declaration throws an exception.

You can use an initializer block to handle this situation.

This is not absolutely necessary, since the initialization could be done in a constructor, where a try ... catch would be legal. But then it would need to be done in every constructor, which someone adding another constructor later might forget.

Initializers are run in the order in which they appear in the code, whether standalone initializers, or initializers in a field declaration so, in the above code:

The Random object gets created for the first field.
The MegaString gets the first generated random number.
x gets the second generated random number.

Static Initializer Blocks

If a field is static, and is populated with a newly constructed object, that object's constructor code will run when the class loads. In our example, if we make the MegaString property static, its constructor will run when the class loads.

Again, this won't compile, but now there is no way even to defer the issue to the constructors, since the element is static.

You can use a static initializer block to handle this problem.

Again, the initializers are run in the order in which they appear in the code, when the class is loaded.

Assertions

Java 1.4 added the concept of assertions, code lines that test that a presumed state actually exists

-If the state is not as presumed, then an AssertionError will be thrown.
-Assertions are not intended for testing values that could be expected; they are intended to be used when it is believed that a state exists, but we are not absolutely sure we have covered all the possible avenues that affect the state.

To use an assertion in code:

The optional messageExpression will be converted to a String and passed as the message to the AssertionError constructor, so it cannot be a call to a function declared as void.

For example, perhaps we are using a third-party function that is specified to return a double value between 0 and 1, but we'd like to guarantee that is the case.

Code Sample:

Java-Exceptions/Demos/AssertionTest.java

If the function returns a value outside of our expected range, like 5.0, the assertion condition will evaluate to false, so an AssertionError will be thrown with the message "thirdPartyFunction value 5.0 out of range."

Note: in a 1.4 compiler, you must inform the compiler that you are compiling your code under Java 1.4 rules to use assertions, using the -source 1.4 command line switch:

In Java 5 and later this is not necessary.

Assertions are used for debugging a program, and usually not enabled for production runs. You must specifically enable assertions when you run the program, by using the command line switch -enableassertions (or -ea).

java -enableassertions ClassName java -ea ClassName

Oracle's "rules" for assertions emphasize that they will be disabled most of the time:

-They should not be used for checking the values passed into public methods, since that check will disappear if assertions are not enabled.
-The assertion code shouldn't have any side effects required for normal operation.

14 - JAVA COLLECTIONS

The Java Collections API is a set of classes and interfaces designed to store multiple objects.

There are a variety of classes that store objects in different ways:

Lists store objects in a specific order.
Sets reject duplicates of any objects already in the collection.
Maps store objects in association with a key, which is later used to look up and retrieve the object (note that if an item with a duplicate key is put into a map, the new item will replace the old item).

The basic distinctions are defined in several interfaces in the java.util package:

Collection is the most basic generally useful interface that most, but not all, collection classes implement.

It specifies a number of useful methods, such as those to add and remove elements, ascertain the size of the collection, determine if a specific object is contained in the collection, or return an Iterator that can be used to loop through all elements of the collection (more on this later).
Methods include: add(Object o), remove(Object o), contains(Object o), iterator().
Note that removing an element removes an object that compares as equal to a specified object, rather than by position.
Collection extends the Iterable interface, which only requires one method, which supplies an object used to iterate through the collection.

The List interface adds the ability to insert and delete at a specified index within the collection, or retrieve from a specific position.
The Set interface expects that implementing classes will modify the add methods to prevent duplicates, and also that any constructors will prevent duplicates (the add method returns a boolean that states whether the operation succeeded or not; i.e., if the object could be added because it was not already there).

Sets do not support any indexed retrieval.

The Map interface does not extend Collection, because its adding, removing, and retrieving methods use a key value to identify an element.

Methods include: get(Object key), put(Object key, Object value), remove(Object key), containsKey(Object key), containsValue(Object value), keySet(), entrySet().
Maps do not support any indexed retrieval.

In addition to the List, Set, and Map categories, there are also several inferences you can make from some of the collection class names:

A name beginning with Hash uses a hashing and mapping strategy internally, although the key values usually have no meaning (the hashing approach attempts to provide an efficient and approximately equal lookup time for any element).
A name beginning with Linked uses a linking strategy to preserve the order of insertion and is optimized for insertion/deletion as opposed to appending or iterating.
A name beginning with Tree uses a binary tree to impose an ordering scheme, either the natural order of the elements (as specified by the Comparable interface implemented by many classes including String and the numeric wrapper classes) or an order dictated by a special helper class object (a Comparator).

Several additional interfaces are used to define useful helper classes:

Enumeration provides a pair of methods that enable you to loop through a collection in a standardized manner, regardless of the type of collection (you test if there are more elements, and, if so, retrieve the next element).

This interface is less frequently used now that the following interface has been added to the API.
But, many of the elements in J2EE (servlets in particular) predate the Iterator concept and were specified to use enumerations, so they will still appear in new code.

Iterator is an improved version that allows an object to be removed from the collection through the iterator.

The following diagrams show some of the classes and interfaces that are available:

Using the Collection Classes

The following are several examples of collection classes:

Vector stores objects in a linear list, in order of addition. Some additional notes on Vector are:

You can insert and delete objects at any location.
All methods are synchronized, so that the class is thread-safe.
Vector predates the collections framework, but was marked to implement List when the collections API was developed

As a result, there are many duplicate methods, like add and addElement, since the names chosen for Collection methods didn't all match existing method names in Vector.

Vector was used extensively in the past, and therefore you will see it in a lot of code, but most recent code uses ArrayList instead.

ArrayList, like Vector, stores objects in a linear list, in order of addition. Methods are not synchronized, so that the class is not inherently thread-safe (but there are now tools in the Collections API to provide a thread-safe wrapper for any collection, which is why Vector has fallen into disuse).

TreeSet stores objects in a linear sequence, sorted by a comparison, with no duplicates. TreeSet also:

Stores Comparable items or uses a separate Comparator object to determine ordering.

Uses a balanced tree approach to manage the ordering and retrieval.

Note that there is no tree list collection, because the concepts of insertion order and natural order are incompatible. Since sets reject duplicates, any comparison algorithm should include a guaranteed tiebreaker (for example, to store employees in last name, first name order: to allow for two Joe Smiths, we should include the employee id as the final level of comparison).

TreeMap stores objects in a Map, where any subcollection or iterator obtained will be sorted by the key values. Note that:

Keys must be Comparable items or have a separate Comparator object.

For maps, an iterator is not directly available. You must get either the key set or entry set, from which an iterator is available.

Hashtable stores objects in a Map. Note also that:

All methods are synchronized, so that the class is thread-safe.

Hashtable predates the collections framework, but was marked to implement Map when the collections API was developed.

Like Vector, Hashtablehas some duplicate methods.

Hashtable extends an obsolete class called Dictionary.

HashSet uses hashing strategy to manage a Set. Note also that:

HashSet rejects duplicate entries.

Entries are managed by an internal HashMap that uses the entry hashCode values as the keys.

Methods are not synchronized.

Using the Iterator Interface

Iterators provide a standard way to loop through all items in a collection, regardless of the type of collection. Note that:

All collection classes implement an iterator() method that returns the object's iterator (declared as Iterator iterator()).

This method is specified by the Iterable interface, which is the base interface for Collection.

For maps, the collection itself is not Iterable, but the set of keys and the set of entries are.

You can use a for-each loop for any Iterable object.

Without an iterator, you could still use an indexed loop to walk through a list using the size() method to find the upper limit, and the get(int index) method to retrieve an item, but other types of collections may not have the concept of an index, so an iterator is a better choice.

There are two key methods supplied by an iterator:

boolean hasNext(), which returns true until there are no more elements.
Object next(), which retrieves the next element and also moves the iterator's internal pointer to it.

Some collections allow you to remove an element through the iterator. The remove method is marked in the docs as optional by the definition of interfaces it has to be present, but the optional status indicates that it may be implemented to merely throw an UnsupportedOperationException.

In any case, if the collection is modified from a route other than via the iterator (perhaps by using remove(int index), or even just using the add method), a ConcurrentModificationException is thrown.

The Enumeration class is an older approach to this concept; it has methods hasMoreElements() and nextElement().

Code Sample:

Java-Collections/Demos/CollectionsTest.java

import java.util.*;

public class CollectionsTest {
  public static void main(String[] args) {
    List l = new ArrayList();
    Map m = new TreeMap();
    Set s = new TreeSet();
    
    l.add(new Integer(1));
    l.add(new Integer(4));
    l.add(new Integer(3));
    l.add(new Integer(2));
    l.add(new Integer(3));
    
    m.put(new Integer(1), "A");
    m.put(new Integer(4), "B");
    m.put(new Integer(3), "C");
    m.put(new Integer(2), "D");
    m.put(new Integer(3), "E");
    
    System.out.println("Adding to Set");
    System.out.println("Adding 1: " + s.add(new Integer(1)));
    System.out.println("Adding 4: " + s.add(new Integer(4)));
    System.out.println("Adding 3: " + s.add(new Integer(3)));
    System.out.println("Adding 2: " + s.add(new Integer(2)));
    System.out.println("Adding 3: " + s.add(new Integer(3)));
   
    System.out.println("List");
    Iterator i = l.iterator();
    while (i.hasNext()) System.out.println(i.next());
    
    System.out.println("Map using keys");
    i = m.keySet().iterator();
    while (i.hasNext()) System.out.println(m.get(i.next()));
    
    System.out.println("Map using entries");
    i = m.entrySet().iterator();
    while (i.hasNext()) System.out.println(i.next());
    
    System.out.println("Set");
    i = s.iterator();
    while (i.hasNext()) System.out.println(i.next());
  }
}

This program demonstrates the three types of collections. As is commonly done, the variables are typed as the most basic interfaces (List, Set, and Map).

We attempt to add the same sequence of values to each: 1, 4, 3, 2, and 3; then:

They are deliberately out of sequence and contain a duplicate.

For the Map, the numbers are the keys, and single-letter strings are used for the associated values.

In the output, first note the true and false values resulting from attempting to add the values to the Set. Also note in the Map listing, which value associated with the key 3 is retained.

An iterator is then obtained for each and the series printed out (for the Map, we try two different approaches: iterating through the keys and retrieving the associated entries, and iterating directly through the set of entries).

Note the order of the values for each, and also which of the duplicates was kept or not. Note also that:

Tthe List object stores all the objects and iterates through them in order of addition.
The Map object stores by key; since a TreeMap is used, its iterator returns the elements sorted in order by the keys.
Since one key is duplicated, the later of the two values stored under that key is kept.
The Set object rejects the duplicate, so the first item entered is kept (although in this case it would be hard to tell from the iterator listing alone which one was actually stored).

Creating Collectible Classes

hashCode and equals

Both the equals(Object) method and hashCode() methods are used by methods in the Collections API. Note also that:

The Map classes use them to determine if a key is already present.
The Set classes use them to determine if an object is already in the set.
All collections classes use them in contains and related methods.

Oracle specifies that the behavior of hashCode should be "consistent with equals", meaning that two objects that compare as equal should return the same hash code. The reverse is not required; two objects with the same hash code might be unequal, since hash codes provide "bins" for storing objects.

This is critical when writing collectible classes. For example, the implementation of HashSet, which should reject duplicate entries, compares a candidate entry's hashcode against that of each object currently in the collection. It will only call equals if it finds a matching hash code. If no hash code matches, it assumes that the candidate object must not match any already present in the set.

Comparable and Comparator

Sorted collections can sort elements in two ways:

By the natural order of the elements - objects that implement the Comparable interface have a natural order.
By using a third-party class that implements Comparator.

compare(Object a, Object b) returns a negative integer, zero, or a positive integer if a is less than, equal to, or greater than b.
equals(Object o), as in Object, is used not to compare the stored values for value, but to determine if two comparator classes can be considered equal. However, note that the behavior of the compare method should be consistent with equals, as Oracle's documentation advises; that is, compare(a, b) should return 0 when a.equals(b) returns true

As an example: TreeSet uses a tree structure to store items. Tthe tree part of the name is just for identifying the algorithm used for storage; you cannot make use of any of the node-related behaviors from the outside. There are several forms of constructors, most notably:

TreeSet() uses the natural order of the items, so they must implement the Comparable interface (and the items should be mutually comparable, to avoid casting exceptions being thrown during a comparison).
TreeSet(Comparator c) - uses the specified Comparator to compare the items for ordering (and, again, the mutually comparable caveat applies).

Code Sample:

Java-Collections/Demos/UseComparable.java

Since String implements Comparable, the names will appear in alphabetical order when we iterate through the set.

The Arrays class provides useful methods for working with arrays, some of which will return a collection backed by the array (the Collections classes contain useful methods for working with collections, some of which perform the reverse operation).

Creating a Comparable Class

Classes that implement the Comparable interface may be stored in ordered collections. They must have a int compareTo(Object other) method to implement the interface. Note the following:

It is said that these objects have a natural order as determined by this method.
The function returns a negative value for this object considered less than the object passed as parameter other, a positive value for this object considered greater than the object passed as parameter other, and 0 if they are equal.
Since this capability is built into the object, it is important that it the results of the compareTo method match with the results of the equals and hashCode methods.

Creating and Using a Comparator Class

Classes that implement the Comparator interface may be also used with ordered collections, but the collection must be constructed with an explicit reference to an instance of the Comparator. The Comparator is a separate class that will compare two instances of your class to determine the ordering.

The interface specifies int compare(Object a, Object b). The function returns a negative value for an object considered less than the object b, a positive value for b considered greater than a, and 0 if they are equal.

It is still important that the results of the compareTo method match with the results of the objects' equals method. Note that you should usually implement this method to avoid "ties" for objects that would not be considered equal. For example, for two different employees who coincidentally have the same name would be returned in an indeterminate order.

Code Sample:

Java-Collections/Demos/UseComparator.java

The compare method of our comparator makes use of the existing compareTo method in String and simply inverts the result. Note that the objects being compared are tested to make sure both are String objects. If the test fails, the method throws a ClassCastException.

Code Sample:

Java-Collections/Demos/UseComparableAndComparator.java

Since all the collections store are references, it will not use a lot of memory to store the same references in different collections. This creates an analog to a set of table indexes in a database

Collections in Java 5.0: Generics

Java 5.0 added the concept of Generics, which allow data types to be parameterized for a class

In earlier versions of Java, the collection methods to store objects all received a parameter whose type was Object. Therefore, the methods to retrieve elements were typed to return Object. To use a retrieved element, you had to typecast the returned object back to whatever it actually was (and somehow you had to know what it actually was).

The collections in Java 5.0 use a special, new syntax where the type of object is stated in angle brackets after the collection class name.

Instead of ArrayList, there is now ArrayList<E>, where the E can be replaced by any type. Within the class, method parameters and return values can be parameterized with the same type.

For example, an ArrayList of String objects would be ArrayList<String>.

Code Sample:

Java-Collections/Demos/GenericCollectionsTest.java

import java.util.*;

public class GenericCollectionsTest {
  
  public static void main(String[] args) {

List<String> ls = new ArrayList<String>();
    
    ls.add("Hello");
    ls.add("how");
    ls.add("are");
    ls.add("you");
    ls.add("today");
    
    // using iterator
    StringBuffer result = new StringBuffer();   
    Iterator<String> is = ls.iterator();
    while (is.hasNext()) 
      result.append(is.next().toUpperCase()).append(' ');
    result.append('?');
    System.out.println(result);
    
    // using for-each loop
    result = new StringBuffer();
    for (String s : ls) result.append(s.toLowerCase()).append(' ');
    result.append('?');
    System.out.println(result);

// old way
    List l = new ArrayList();
    
    l.add("Hello");
    l.add("how");
    l.add("are");
    l.add("you");
    l.add("today");
    
    // using iterator
    result = new StringBuffer();
    Iterator i = l.iterator();
    while (i.hasNext()) 
      result.append(((String)i.next()).toUpperCase()).append(' ');
    result.append('?');
    System.out.println(result);
    
    // using for-each loop
    result = new StringBuffer();
    for (Object o : l) 
      result.append(((String)o).toLowerCase()).append(' ');
    result.append('?');
    System.out.println(result);

}
}

As you can see, the objects retrieved from the ArrayList are already typed as being String objects. Note the following:

We need to have them as String objects in order to call toUpperCase, whereas our previous examples only printed the objects, so being typed as Object was okay.
Without generics, we must typecast each retrieved element in order to call toUpperCase.
To use an iterator, we would declare the variable to use the same type of element as the collection we draw from, as in Iterator<String>.

Bounded Types

A type parameter may set bounds on the type used, by setting an upper limit (in inheritance diagram terms) on the class used. The extends keyword is used to mean that the class must either be an instance of the specified boundary class, or extend it, or, if it is an interface, implement it:

In the first case, the class may be parameterized with Employee, or any class that extends Employee. In the second, the class may be parameterized with Payable or any type that implements the Payable interface.

Extending Generic Classes and Implementing Generic Interfaces

When extending a generic class or implementing a generic interface, you can maintain the generic type, as in public class ArrayList<T> implements List<T>. In this case, types are still stated in terms of T.

You can lock in the generic type: public class EmployeeList extends ArrayList<Employee> or public class StringList implements java.util.List<String>. In these cases, methods would use the fixed type. For example, if you overrode add(E) in ArrayList<E> in the above EmployeeList, it would be add(Employee).

Generic Methods

Methods may be generic, whether or not they are in a generic class. The syntax is somewhat ugly, since it requires listing the type variable before the return type and requires that at least one parameter to the method be of the generic type (that is how the compiler knows what the type is).

The above method is parameterized with type T. The type for T is established by whatever type of array is passed in; if we pass in a String array, then T is String. The method will then randomly pick one to return.

The type may be bounded with extends.

Variations on Generics - Wildcards

In the documentation for a collections class, you may see some strange type parameters for methods or constructors, such as:

he question mark is a wildcard, indicating that the actual type is unknown. But, we at least know limits in the second two cases. The extends keyword in this usage actually means "is, extends, or implements" (which is the same criteria the instanceof operator applies). The super keyword means essentially the opposite: that the type parameter of the other class is, or is more basic than, this class's type. The usages with extends and super are called bounded wildcards.

This syntax only occurs when the variable is itself a generic class. The wildcards then state how that class's generic type relates to this class's type.

Why this is necessary leads down a long and winding path. To start, consider the following:

This seems reasonable at first glance, but then consider if this line followed:

<textarea>exEmps.add(new ContractEmployee());</textarea>

Perfectly legal as far as the compiler is concerned, since ContractEmploye fits within the Employee type that the exEmps variable requires, but now we have a contract employee in a list instance that is supposed to hold only exempt employees. So, an instance of a class parameterized with a derived class is not an instance of that class parameterized with the base class, even though individual instances of the derived class can be used in the base-parameterized generic class; e.g., our List<Employee> can add individual exempt employees.

For the first wildcard case above, public boolean containsAll(Collection<?> c), it does no harm for us to see if our collection contains all the elements of some other collection that may contain an entirely unrelated type (but few, if any, of the items would compare as equal). Note that the contains method accepts an Object parameter, not an E, for this same reason.

The extends term in public boolean addAll(Collection<? extends E> c)means that the unknown class is, extends, or implements the listed type. For instance, we could add all the elements of an ArrayList<ExemptEmployee> to an ArrayList<Employee>. That makes sense, since we could add individual exempt employees to a basic employee collection. But, since we don't actually know what the parameterized type of the incoming collection is (it is the ? class), we cannot call any methods on that object that depend on its parameterized type. So we can't add to that collection; we can only read from it.

The super term is seen less often; it means that the parameterized type of the incoming collection must be of the same type or a more basic type. The TreeSet constructor can accept a Comparator for its actual type, or any type more basic (e.g., a Comparator<Object> can be used for a TreeSet of anything, since its compare method will accept any type of data). It is, however, likely that many "acceptable" comparators will end up throwing a ClassCastException at runtime if they can't actually compare the types involved. So, for example, if we had a Comparator<Employee> class that compared employee ids, we might still wish to use it in a TreeSet<ExemptEmployee>, where it would be perfectly valid (in fact, it would be an annoyance to have to write a special comparator for every employee type, if all the comparators did was compare the ids).

Payroll Using Generics

Duration: 15 to 25 minutes.
We can modify our payroll application to use generic lists instead of arrays for our employees, invoices, and payables.

Make the Employee[] variable a List<Employee>, and populate it with a new ArrayList<Employee>.</Employee>
Since lists have no fixed size, you will need to change the first for loop, perhaps to a fixed number of iterations.</Employee>
Modify the lines that add employees from using array indices to using the add method.</Employee>
Turn the Invoice[] into a List<Invoice> populated with a Vector<Invoice>, similar to what we did in we did in step 1.</Invoice>
Modify the lines that populate that list.</Invoice>
Create an ArrayList<Payable> in a List<Payable> payables variable.</Payable>
Create an ArrayList<Payable> in a List<Payable> payments variable.</Payable>
Then call that list's addAll method once and pass in the employee list.</Payable>
Then add all the invoices the same way.</Payable>
Since we might not want to modify CheckPrinter, you can generate a Payable array for it with:</Payable>

The parameter is a "dummy" array used to tell the generic method what type of array to create. Note in the Collection documentation that this method is typed with T rather than the E used in the rest of the class. This method has its own local type, which is determined by the type of the array passed in.

Solution:

Solutions/Payroll-Collections01/Payroll.java

import employees.*;
import vendors.*;
import util.*;
import finance.*;
import java.util.*;

public class Payroll {	
	public static void main(String[] args) {
		List<Employee> e = new ArrayList<Employee>();
		Employee empl = null;
		String fName = null;
		String lName = null;
		int dept = 0;
		double payRate = 0.0;
		double hours = 0.0;

for (int i = 0; i < 5; i++) {
			try {
 				char type = 
					KeyboardReader.getPromptedChar("Enter type: E, N, or C: ");
				if (type != 'e' && type != 'E' && 
						type != 'n' && type != 'N' && 
						type != 'c' && type != 'C') {
					System.out.println("Please enter a valid type");
					i--;
					continue; 			 
				}
				fName = KeyboardReader.getPromptedString("Enter first name: ");
				lName = KeyboardReader.getPromptedString("Enter last name: ");
	      dept = KeyboardReader.getPromptedInt(
	      			"Enter department: ", "Department must be numeric",
	      			new DeptValidator(), "Valid departments are 1 - 5");
				do {
					payRate = KeyboardReader.getPromptedDouble("Enter pay rate: ", 
									"Pay rate must be numeric");
					if (payRate < 0.0) System.out.println("Pay rate must be >= 0");
				} while (payRate < 0.0);
	
				switch (type) {
					case 'e':
					case 'E': 
						empl = new ExemptEmployee(fName, lName, dept, payRate);
						e.add(empl);
						break;
					case 'n':
					case 'N': 
						do {
							hours = KeyboardReader.getPromptedDouble("Enter hours: ");
							if (hours < 0.0) 
								System.out.println("Hours must be >= 0");
						} while (hours < 0.0);
						empl = new NonexemptEmployee(fName,lName,dept,payRate,hours);
						e.add(empl);
						break;
					case 'c':
					case 'C': 
						do {
							hours = KeyboardReader.getPromptedDouble("Enter hours: ");
							if (hours < 0.0) 
								System.out.println("Hours must be >= 0");
						} while (hours < 0.0);
						empl = new ContractEmployee(fName,lName,dept,payRate,hours);
						e.add(empl);
				}
 
				System.out.println(empl.getPayInfo());
			} catch (InvalidValueException ex) {
					System.out.println(ex.getMessage());
					i--;	//failed, so back up counter to repeat this employee
				}
		}
 	
		System.out.println();
		System.out.println("Exempt Employees");
		System.out.println("====== =========");
		for (Employee emp : e) {
			if (emp instanceof ExemptEmployee) {
				System.out.println(emp.getPayInfo());
			}
		}
		System.out.println();
		System.out.println("Nonexempt Employees");
		System.out.println("======== =========");
		for (Employee emp : e) {
			if (emp instanceof NonexemptEmployee) {
				System.out.println(emp.getPayInfo());
			}
		}
		System.out.println();
		System.out.println("Contract Employees");
		System.out.println("======== =========");
		for (Employee emp : e) {
			if (emp instanceof ContractEmployee) {
				System.out.println(emp.getPayInfo());
			}
		}

List<Invoice> inv = new Vector<Invoice>();
		inv.add(new Invoice("ABC Co.", 456.78));
		inv.add(new Invoice("XYZ Co.", 1234.56));
		inv.add(new Invoice("Hello, Inc.", 999.99));
		inv.add(new Invoice("World, Ltd.", 0.43));

List<Payable> payments = new ArrayList<Payable>();
		payments.addAll(e);
		payments.addAll(inv);

CheckPrinter.printChecks( payments.toArray(new Payable[] { }) );
	}
}

Notice that we didn't have to change the for-each loops; they work equally well for Iterable objects, like lists, as they do for arrays.

Also, the addAll method accepts any Collection, so it can take an ArrayList or a Vector equally well. And, since it accepts Collection<? extends E>, it can take collections of either Employee or Invoice (both implement the Payable type used for E in the the receiving collection).

15 - JAVA INNER CLASSES

Inner Classes, aka Nested Classes

Inner classes, also known as nested classes are classes defined within another class.

They may be defined as public, protected, private, or with package access.

They may only be used "in the context" of the containingclass (outer class, or enclosing class), unless they are marked as static.

The outer class can freely instantiate inner class objects within its code; they are automatically associated with the outer class instance that created them.
Code in some other class can instantiate an inner class object associated with a specific instance of the outer class if the inner class definition is public (and its containing class is public as well).
If the inner class is static, then it can be instantiated without an outer class instance, otherwise, the inner class object must be attached to an instance of the outer class.
Create a type of object that is only needed within one class, usually for some short-term purpose.
Create a utility type of object that cannot be used elsewhere (which would allow the programmer to change it without fear of repercussions in other classes).
Create one-of-a-kind interface implementations (such as individualized event handlers).
Allow a sort of multiple inheritance, since the inner class may extend a different class than the outer class extends, and an inner class instance would have access to its private elements as well as the private elements of the outer class object it is attached to
Implement one-to-many relationships where the classes are tightly coupled (meaning that code for one or both of the classes needs access to many of the private elements of the other class) - the outer class would be the "one" side of the relationship, with the inner class being the "many" side.
Provide a specialized form of callback, with which a class may pass very limited access to some of its internal components. Note that:

The collections classes provide an iterator, a class that implements the Iterator interface to loop through the elements in the collection using hasNext and next methods.
Given that the internal structure of the collection may be complex, implementing the iterator as an inner class enables it to navigate the structure, while not exposing any other aspects of the collection to the outside world.

Inner class code has free access to all elements of the outer class object that contains it, by name (no matter what the access level of the elements is). Outer class code has free access to all elements in any of its inner classes, no matter what their access term.

An inner class compiles to its own class file, separate from that of the outer class (the name of the file will be OuterClassName$InnerClassName.class, although within your code the name of the class will be OuterClassName.InnerClassName); you cannot use the dollar sign version of the name in your code.

An inner class occupies its own memory block, separate from the outer class memory block.

An inner class may extend one class, which might be unrelated to the class the outer class extends.

An inner class can implement one of more interfaces, and, if treated as an instance of one of its interfaces, external code may have no knowledge that the object actually comes from an inner class.

Inner Class Syntax

The definition of the inner class is always available for the outer class to use. Note that:

No inner class objects are automatically instantiated with an outer class object.
Outer class code may instantiate any number of inner class objects - none, one, or many.

Code Sample:

Java-InnerClasses/Demos/MyOuter.java

This is a simple example of an inner class

MyOuter has one property, x; the inner class MyInner has one property, y.
The MyOuter constructor accepts two parameters; the first is used to populate x.
It creates one MyInner object, whose y property is populated with the second parameter.
Note that the inner class has free access to the private outer class x element.
The outer class has free access to the private inner class privateDisplay() method.

The connection between the two classes is handled automatically.

The following diagram maps out the memory used by the example.

Instantiating an Inner Class Instance from within the Enclosing Class

An inner class instance may be directly instantiated from code in the enclosing class, without any special syntax:

Such an instance is automatically associated with the enclosing class instance that instantiated it.

Code Sample:

Java-InnerClasses/Demos/Inner1.java

This code simply creates an instance of the outer class, MyOuter.

The MyOuter constructor creates an instance of MyInner as mentioned earlier.

Inner Classes Referenced from Outside the Enclosing Class

If the access term for the inner class definition is public (or the element is accessible at package access or protected level to the other class), then other classes can hold references to one or more of these inner class objects

If the inner class is static, then it can exist without an outer class object, otherwise any inner class object must belong to an outer class instance.

For code that is not in the outer class, a reference to a static or non-static inner class object must use the outer class name, a dot, then the inner class name:

If the inner class has an accessible constructor, you can you instantiate one from outside of the enclosing class, although the syntax is ugly, and there is rarely a need for this capability.

Referencing the Outer Class Instance from the Inner Class Code

If inner class code needs a reference to the outer class instance that it is attached to, use the name of the outer class, a dot, and this. Remember that if there is no name conflict, there is no need for any special syntax.
For code in MyInner to obtain a reference to its MyOuter:

static Inner Classes

An inner class may be marked as static.

A static inner class my be instantiated without an instance of the outer class. Note that:

static members of the outer class are visible to the inner class, no matter what their access level.
Non-static members of the outer class are not available, since there is not instance of the outer class to retrieve them from.

To create a static inner class object from outside the enclosing class, you must still reference the outer class name

An inner class may not have static members unless the inner class is itself marked as static.

Code Sample:

Java-InnerClasses/Demos/StaticInnerTest.java

We have a class StaticOuter that declares a static inner class StaticInner. StaticOuter has a method that will create instances of StaticInner. But, StaticInner also has a public constructor. Note that:

We can directly instantiate a StaticOuter.StaticInner object without an outer class instance.
Code for a StaticOuter can create a StaticInner, but the inner class object has no attachment to the outer class object that created it.
Note the commented out line; you cannot create a static inner class instance attached to an instance of its enclosing class.

Better Practices for Working with Inner Classes

It is easiest if inner class objects can always be instantiated from the enclosing class object. You can create a factory method to accomplish this.

Code Sample:

Java-InnerClasses/Demos/FactoryInnerOuter.java

class FactoryOuter {
  FactoryInner[] fi = new FactoryInner[3];
  protected int lastIndex = 0;
  private int x = 0;
  public FactoryOuter(int x) {
    this.x = x;
  }
  public int getX() {
    return x;
  }
  public void addInner(int y) {
    if (lastIndex < fi.length) {
      fi[lastIndex++] = new FactoryInner(y);
    } 
    else throw new RuntimeException("FactoryInner array full");
  }
  public void list() {
    for (int i = 0; i < fi.length; i++) {
      System.out.print("I can see into the inner class where y = " + 
                       fi[i].y + " or call display: ");
      fi[i].display();      
    }
  }
  public class FactoryInner {
    private int y;
    protected FactoryInner(int y) {
      this.y = y;
    }
    public void display() {
      System.out.println("FactoryInner x =  " + x + " and y = " + y);
    }
  }
}
public class FactoryInnerOuter {
  public static void main(String[] args) {
    FactoryOuter fo = new FactoryOuter(1);
    fo.addInner(101);
    fo.addInner(102);
    fo.addInner(103);
    fo.list();
    //fo.addInner(104);
  }
}

For convenience, this file contains both the main class and the FactoryOuter class (with package access). Note that:

An instance of FactoryOuter contains a three element array of FactoryInner objects.

The addInner method instantiates a FactoryInner object and adds it to the array (note that is still automatically associated with the FactoryOuter instance by the JVM, but we need our own mechanism for keeping track of the inner class instances we create).

A better approach would be to use one of the collections classes instead of an array, to avoid running out of room in the array

This is exactly the sort of thing that happens when you obtain an iterator from a collection class. In order to successfully navigate what is most likely a complex internal structure, the object will need access to the private elements. So, an inner class is used, but all you need to know about the object is that it implements the Iterator interface.

Code Sample:

Java-InnerClasses/Demos/PayrollInnerClass/employees/Employee.java

package employees;
import finance.TransactionException;

public class Employee {

---- C O D E   O M I T T E D ----
  private double ytdPay;
  private Payment[] payments = new Payment[12]; 
  private int paymentCount = 0;

---- C O D E   O M I T T E D ----
  public double getYtdPay() { return ytdPay; }
  
  public Payment createPayment() {
    Payment p = new Payment(payRate);
    payments[paymentCount++] = p;
    return p;
  }

public void printPaymentHistory() {
    for (Payment p : payments) {
      System.out.println(p);
    }
  }
  
  public class Payment {
    private double amount;
    private boolean posted;
    
    public Payment(double amount) {
      this.amount = amount;
    }

public boolean process() throws TransactionException {
      if (!posted) {
        ytdPay += amount;
        posted = true;
        System.out.println(getFullName() + " paid " + amount);
        return true;
      } else {
        throw new TransactionException("Transaction already processed");
      }
    }
    
    public String toString() {
      return getFullName() + " payment of " + amount;
    }
    
  } 
}

Payment is an inner class to a simplified Employee, and, as an inner class, has free access to all private elements of Employee. Unlike a standalone payment class, this class can retrieve the employee name from the outer class instance. We also use this access to defer updating the year-to-date amounts until the payment is posted, via the process method.

To get this degree of interaction between two separate classes would be difficult, since it would mean that either:

The ability to update ytdPay would have to be publicly available.
Employee and Payment would have to be in the same package, with updating ytdPay achieved by using package access.

Note that we have also separated the concepts of creating a payment from actually posting it. This gives us better control over transactions - note that a payment cannot be processed twice.

Code Sample:

Java-InnerClasses/Demos/PayrollInnerClass/Payroll.java

We have only one employee for simplicity. As we loop for each month, a payment is created for each. We try to process the June payment twice (remember that the array is zero-based, so January is month 0; this matches the behavior of the java.util.Date class) . The second attempt to process the payment should throw an exception which our catch block handles.

We retrieve and print the year-to-date pay each time we process a payment.

At the end, we have the Employee object print the entire payment history created by our calls to the inner class' process method..

Code Sample:

Java-InnerClasses/Demos/PayrollInnerClassInterface/employees/Employee.java

This code goes one step further to create a Payment inner class that implements the Payable interface.

Code Sample:

Java-InnerClasses/Demos/PayrollInnerClassInterface/Payroll.java

The only difference here is that we declare the variable holding the payments as Payable, hiding the fact that it is an inner class.

Enums

In Java 5, the enum element was introduced. Long sought by the C/C++ part of the Java community, enums provide a set of predefined constants for indicating a small set of mutually exclusive values or states.

Why Another Syntax Element for a Set of Constants?

The other approaches all have some sort of flaw, particularly as involves type-safety.

Interfaces defining only constants were commonly used, and several are grandfathered into the API, like SwingConstants. But, there is a minor problem that if you implement an interface in order to gain the constants, you then have additional public elements in that class that you wouldn't really want to provide to the outside world. public class MyFrame extends JFrame implements SwingConstants { . . . } MyFrame frame = new MyFrame(); // frame.HORIZONTAL is now publicly available public class MyFrame extends JFrame implements SwingConstants { . . . } MyFrame frame = new MyFrame(); // frame.HORIZONTAL is now publicly available
Using plain old integers seems straightforward enough, but, if you perhaps have a method that requires one of that set of values to be passed in, the parameter would be typed as int. A caller could supply any int value, including ones you wouldn't expect. private int LEFT = 0; private int RIGHT = 1; private int CENTER = 2; public void setAlignment(int align) { ... } // compiler would allow: setAlignment(99);

Java enums provide a type-safe way of creating a set of constants, since they are defined as a class, and therefore are a type of data.

A disadvantage to this approach is that the set of values is written into the code. For sets of values that may change, this would require recompiling the code, and would invalidate any serialized instances of the enum class. For example, if we offered a choice of benefits plans to our employees, the set of available plans would not be a good candidate for an enum, since it is likely that the set of available plans would eventually change.

Defining an enum Class

To create a simple enum class:

Declare like an ordinary class, except using the keyword enum instead of class.
Within the curly braces, supply a comma-separated list of names, ending in a semicolon.

One instance of the enum class will be created to represent each item you listed, available as a static field of the class, using the name you supplied which will be the individual values. Each instance can provide an integral value, with sequential indexes starting at 0, in the order that the names were defined - there is no way to change this, but there is a route to get specific values which have a complex internal state.

There will be three instances of the class created, Alignment.left, Alignment.right, and Alignment.center. An Alignment type variable can hold any of these three values.

Enums automatically extend the Enum class from the API, and they inherit several useful methods:

Each object has a name method that returns the name of that instance (as does the toString method).
The ordinal method returns that enum object's position in the set, the integer index mentioned above.

There are also several other methods that will be present, although they are not listed in the documentation for Enum.

A public static EnumName[] values() method that returns an array containing all the values, in order (so that the array index would match the ordinal value for that object). This method is not inherited, but is built specifically for each enum class.
A public EnumName valueOf(String name) method that returns the instance whose name matches the specified name (this is not the uglier method you will see in the documentation, but another built specifically for each instance - the one listed in the documentation is actually used internally by the simpler form).

The reason for the last two methods not being in the documentation has to do with generics and type erasure - the methods cannot be declared in the Enum base class in a way that would allow the use of the as-yet unknown subclass.

Individual values from the set may be accessed as static elements of the enum class. The JVM will instantiate exactly one instance of each value from the set. Therefore, they can be used in comparisons with ==, or in switch statements (using the equals method is preferred to ==, since it will serve as a reminder that you are dealing with true objects, not integers).

Although enums may be top-level classes, they are often created as inner classes, as in the following example, where the concept of the enum is an integral part of a new BookWithEnum class. When used as an inner class, they are automatically static, so that an instance of an inner enum does not have access to instance elements of the enclosing class.

Code Sample:

Java-InnerClasses/Demos/BookWithEnum.java

public class BookWithEnum {
  private int itemCode;
  private String title;
  private double price;
  private Category category;
  
  public enum Category { required, supplemental, optional, unknown };
  
  public BookWithEnum(
        int itemCode, String title, 
        double price, Category category) {
    setItemCode(itemCode);
    setTitle(title);
    setPrice(price);
    setCategory(category);
  }
  public BookWithEnum(String title) {
    setItemCode(0);
    setTitle(title);
    setPrice(0.0);
    setCategory(Category.unknown);
  }
  public int getItemCode() {
    return itemCode;
  }
  public void setItemCode (int itemCode) {
    if (itemCode > 0) this.itemCode = itemCode; 
  }
  public String getTitle() {
    return title;
  }
  public void setTitle (String title) {
    this.title = title;
  }
  public void setPrice(double price) {
    this.price = price;
  }
  public double getPrice() {
    return price;
  }
  public void setCategory(Category category) {
    this.category = category;
  }
  public void setCategory(String categoryName) {
    this.category = Category.valueOf(categoryName);
  }
  public Category getCategory() {
    return category;
  }
  public void display() {
    System.out.println(itemCode + " " + title + ": " + category +
          ", Price: $" + price);
  }
}

The Category enum is defined as an inner class to BookWithEnum. The full names of the complete set of values are: BookWithEnum.Category.required, BookWithEnum.Category.supplemental, BookWithEnum.Category.optional, and BookWithEnum.Category.unknown. From within the BookWithEnum class, they may be accessed as: Category.required, Category.supplemental, Category.optional, and Category.unknown.

We set the category for a book constructed without one as Category.unknown, and provide methods to get the value, and to set it with either an enum object or from a string.

Note that enums may be used in switch statements - for the cases you use only the short name for the value.

More Complex Enums

Enums are more than just a set of integer constants. They are actually a set of unique object instances, and, as objects, can have multiple fields. So, an enum is a class with a fixed number of possible instances, each with it's own unique state, and each of the possible instances is created automatically and stored as static field under the same name. (In design pattern terms, an enum is a Flyweight - a class where only a limited number of fixed states exist.)

To create a more complex enum class:

Declare as before.
Declare any additional fields and accessor methods as with a regular class. While you can actually write mutator methods to create what is called a mutable enum, this practice is strongly discouraged.
Write one constructor.
Within the curly braces, again supply a comma-separated list of names, which will be the individual values, but this time with a parameter list. The enum values will be constructed with the data you provide.