Java tutorial
This guide was written to help people with no Java experience get into the more advanced functions offered via the skin interface, for example the ability to write beanshell scripts (interpreted Java). This guide was very kindly written by Laura Seabrook and was previously posted to the forum. It is now presented here as a permanent reference.
You can run Java code samples interactively in the "jAlbum console window" available from the help menu.
This guide is broken down into four sections as follows:
| Contents |
|---|
1. Literals, Variables and Expressions
I'm writing this for people who, like me, aren't that familiar with Java as a programming language, but would like to use some of it to customise their jAlbum skins. I'm no expert -- in fact until I downloaded jAlbum I hadn't even looked at ANY Java coding. This is not a full tutorial because I don't know that much, but hopefully it will help you get started. The following has been culled from various books explaining Java, and from other topics in the forums, and repeats information from the help pages as well.
Scriptlets
The first thing to realise is that you can include Beanshell scripts directly on the htt pages. Beanshell is just a "shell" under which Java codes can be written and evaluated directly. To write such code, you need to place it like so...
<% CODE GOES HERE; %>
or
<% CODE GOES HERE %>
...in the location on the page that you want it to be evaluated. Within the section between the "<%" and "%>", you can place Java statements. Basically you put one statement per line, and end it with a ";", like...
userVar1 = 45; uservar2 = userVar1 + 6;
If you DON'T put the semicolon at the end of a the statement, you'll probably get an error message when you try to generate an album -- the message will vary depending upon what the next statement is. It's also possible to place code in "blocks" delimited by curly brackets, e.g.
{
LINE ONE OF CODE;
LINE TWO OF CODE;
LINE THREE OF CODE;
}
This comes in handy for IF statements (See PART 2 for details) because then a single IF can activate several lines of code. You can create a label by placing a colon after the label's name, e.g.
section_one: section_two: STATEMENT;
...these can be handy for later documentation, and also breaking out of loops. You can also comment out bits of code in two ways:
// All code on this line is ignored /* This is a block of comments that get ignored by Java until it is closed. */
The other important scriptlet to know is the EVAL function. Anything written like...
<%= EXPRESSION %>
...will return whatever value is indicated in the EXPRESSION listed. This might be a simple variable, like "userVar1", or something more complex like "filename.lastIndexOf('.')". This is important because if you're going to create and manipulate variables in a script, you need a way of putting the results into HTML codes.
Literals
Java uses literals and variables to assign and indicate values. A Literal has a fixed value, whereas variables can be changed. There are four types of literals.
Boolean
A boolean literal is either true or false, and is used to test/assign a result. e.g.
fileTest = '''false''';
Characters & Strings
A character literal is a single printable character and is indicated by putting single quotes around the character. e.g
'A' // The "A" character '?' // The "?" character '\u0041' // The "A" character '\u0022' // The double quote character
...the last two lines show "Unicode" characters. The value (in hex) after the "\u" is a special code for the character. You will need to look up a java reference for a full list of codes. If you use "\" instead of "\u", you can insert an octal (base 8) character as well, for example...
'\101' // The "A" character (again) '\060' // The "0" character (zero)
It is also possible to use a "special character escape sequence" which is a special code after the "\" character. The codes are:
'\\' backslash // Not to be confused with the comments code '\"' double quote '\'' single quote '\b' backspace '\f' Form feed '\n' newline '\r' carriage return '\t' horizontal tab
Strings are consist of zero or more characters surrounded by double quotes. Note in the examples below how escape codes can be used in a string:
"" // Gives an empty string of no characters "This is a test string" // Has a value of: This is a test string "This is a \"test\" string" // Has a value of: This is a "test" string "The value was \060" // Has a value of: The value was 0
Numbers
Java supports floating point, integer and byte literals (and variables). There are different types of floating point literals (and variables) but what concerns us here is how to represent them. A floating point number can have an exponent (shown by using "E" or "e") and a type suffix ("F" or "f" for single precision, "D" or "d" for double precision):
6.5E+3 (or 6.5E3) // 65000.0 double precision 7D // 7.0 double precision .01f // .01 single precision
Integers can be shown as a series of digits, followed by an optional suffix ("L" or "l" for long integer types). a prefix of "0x" indicates that the number is hex based (digits 0-9, and letters A-F), and a prefix of "0" indicates that it's octal based (digits 0-8). e.g.
76 // Integer 76 // Long Integer 0x4a // Hexidecimal number 057 // Octal number that is a long integer
There is also a short integer type and a byte type, but in practice there's no difference in setting them than with a regular integer (see variables).
Null
A null literal represents no value and is simply listed as null. There is a difference between 0 (zero), "" (no string value) and null. The first two are actual values, whereas null isn't, You can use null in testing to see if a value has been set, e.g.
if (newTitle != null) title = newTitle; // Assign newTitle to title, if it value
Variables
Simple variables (anything not an array or object) have values assigned to them, or re-assigned as needs to be. The variety of variable types matches the type of literals. A variable has to be assigned a value otherwise it has a "null" or "void" value. Assignments are made in the form of...
TYPE VARIABLE [, VARIABLE];
or [TYPE] VARIABLE = [VARIABLE = ] VALUE;
...where TYPE is the type of variable to be created (this is optional, hence the brackets), VARIABLE is the name of the variable to be assigned (e.g. userVar1), and VALUE is either a literal or an expression to be evaluated (e.g. userVar2+1 or "default"). All the following assign variables:
boolean test1, fileExists // Sets boolean variables test1 and fileExists userVar = "fred" // assigns "fred" to a string variable called userVar byte thumbX = thumbY = 0 // assigns 0 to byte variables thumbX and thumbY
If you don't explicitly give the variable a type, it will be assumed to of a type that matches the value assigned to it. e.g.
userVar = 44 // integer number userVar = 44.5 // floating point number userVar = 44D // double precision floating point number userVar = 'E' // character userVar = "test" // string userVar = true // boolean
...however, you can also assign the type with a prefix. e.g.
boolean limit = (n>5) // true if n is greater than 5, otherwise false byte posXRay = -33 // a number between -128 to 127 char tabChar = '\t' // assigns the TAB character to a character variable double energy = mass*velocity // a value between +/- 4.9 times 10^324 power float yPos = 2.0345 // a value between +/- 1.4 times 10^45 power int timeSec = distX-16000 // a value between +/- 2,147,483,647 long tempSol = 44.56 // a value between +/- 9 times 10^18 power short userVar = 1533 // a value between +/- 32,767 String userVar = preFix + sufFix // a concatenated value of strings preFix & sufFix
Normally you wouldn't be using more than three types of variables in jAlbum: boolean, integer and String. The other types still exist though. The main different in the types of number variables is how much space each occupies. The short variable only takes up two bytes of storage, whereas a double takes up eight.
Expressions
Assignments are actually a form of expression, where values can be manipulated and checked. Basically expressions will be either numeric, logical, character or string based. Expressions have OPERATORS and OPERANDS. The OPERAND is a value or variable, and the OPERATOR is a symbol that tells you what to do with the OPERANDS. e.g. in...
userVar1 * 44
...userVar1 and 44 are the OPERANDS and the "*" symbol (for multiplication) is the OPERATOR.
Maths
Basic maths is supported in Java as per the following functions:
testA * testB // result is testA times TestB testA / testB // result is testA divided by TestB testA - testB // result is testA minus TestB testA + testB // result is testA plus TestB testA % testB // result is remainder of testA divided by TestB e.g. 20%6 = 2, 20%7 = 6, and 20%10 = 0
The "=" in assignment determines how the value is assigned to the variable, and there are variants to "=". The following examples show some of these:
userVar1 += userVar2 // equivalent of userVar1 = userVar1 + userVar2 userVar1 -= userVar2 // equivalent of userVar1 = userVar1 - userVar2 userVar1 /= userVar2 // equivalent of userVar1 = userVar1 / userVar2 userVar1 *= userVar2 // equivalent of userVar1 = userVar1 * userVar2 userVar1 ^= userVar2 // equivalent of userVar1 = userVar1 ^ userVar2 userVar1 %= userVar2 // equivalent of userVar1 = userVar1 % userVar2
You can also increase or decrease a variable by 1 using the following:
userVar1 ++; // equivalent to userVar1 = userVar1 + 1 userVar1 --; // equivalent to userVar1 = userVar1 - 1
If you want more complex mathematic, you have to call a Maths method to do it. Some methods are...
Math.abs(uVar3) // returns the absolute value of uVar3
e.g. Math.abs(-4) = 4
Math.max(uVar1, uVar2) // returns the maximum of the two values
e.g. Math.max(3, -1) = 3
Math.min(uVar1, uVar2) // returns the minimum of the two values
e.g. Math.min(3, -1) = -1
Math.pow(uVar1, uVar2) // raises uVar1 to the power of uVar2
e.g. Math.pow(2,3) = 2*2*2 = 8
Math.sqrt(uVar3) // equals the square root of uVar3
e.g. Math.sqrt(9) = 3
Math.round(uVar3) // results in a rounding of uVar3 to the nearest integer
e.g. Math.round(5.321)= 5
Math.random() // equals a double precision number between 0 and 1. e.g.
int result = (int) (Math.random()*uVar3)+1
...will result in a random integer between 1 and uVar3
There are other methods too, such as "acos", but it's unlikely that you'd need them to create an album.
Parenthesis
You can enclose parts or a whole of an expression in parenthesis, and this will affect the order in which the OPERATORs affect the OPERANDS, otherwise everything gets resolved more or less from left to right, though multiplication (*) and division (/) have a higher precedence than addition (+) and subtraction (-). e.g.
8 + 3 * 2 // result = 14
(8 + 3) * 2 // result = 22
Parenthesis are also used to specify an expression for testing, like...
(userTest > 5) // result is true if userTest is over 5, otherwise is false
See Part 2-- Decision Structures for more detail.
Characters
Characters can be manipulated using Char methods, like...
cVar = Character.toLowerCase("A") // character cVar is set to "a"
cVar = Character.toUpperCase("a") // character cVar is set to "A"
Strings
String variables can be concatenated, like...
userVar = "123" + "ABC" // results in a value of "123ABC"
They can also be manipulated by using methods:
sVar = String.toLowerCase("A Test") // character sVar is set to "a test"
sVar = String.toUpperCase("A Test") // character sVar is set to "A TEST"
A more extensive list of methods you can use is given in Part 3 -- Methods List.
Conditional Operator
This is an operator which can set up alternative results. The form is:
(CONDITION ? EXPRESSION1 : EXPRESSION2)
Two examples are...
xPos1 = (xPos>xLimit ? 0 : xPos )
...sets xPos1 to xPos, unless it's over xLimit in which case, set it to 0 (zero), and...
strVar = (strVal.equals("default") ? "red" : "green")
...sets strVar to "red" if StrVal equals "default", otherwise it is set to "green".
2. Decision Structures
Control Structures are used to control the flow of activity in a script. There are several useful statements you can use to create such structures, like IF, FOR and DO. Many use boolean conditions to determine actions. This part explains briefly how each work.
Boolean conditions
You can test whether a condition is either true of false, and use that condition in statements. Basically a conditional test is placed within parenthesis:
(userTest > 5) // result is true if userTest is over 5, otherwise is false
Maths Testing
When testing numeric variables or literals, the following "operators" can be used in the condition's expression:
uVar1 == uVar2 // true if uVar1 is equal to uVar2 uVar1 != uVar2 // true if uVar1 is NOT equal to uVar2 uVar1 < uVar2 // true if uVar1 is less than uVar2 uVar1 <= uVar2 // true if uVar1 is less than or equal to uVar2 uVar1 > uVar2 // true if uVar1 is more than uVar2 uVar1 >= uVar2 // true if uVar1 is more than or equal to uVar2
Character Testing
Character variables can be tested using the following methods:
Character.isDigit(cVar) // true if cVar is a digit Character.isLetter(cVar) // true if cVar is a letter Character.isLetterorDigit(cVar) // true if cVar is a letter or digit Character.isLowerCase(cVar) // true if cVar is in lower case Character.isUpperCase(cVar) // true if cVar is in upper case Character.isSpace(cVar) // true if cVar is the space character " "
and
cVar.equals(VALUE) // true if cVar equals VALUE
Note that the isDigit and isLetter methods are based on unicode, not ASCII values, so that code values in different values are equally valid, is formatted in unicode.
String Testing
String variables can be tested with the following methods (assume that strVar is set to "aValue.txt"):
strVar.equals(VALUE) // true if strVar is the EXACTLY the same as VALUE
e.g. VALUE = "aValue.txt"
strVar.equalsIgnoreCase(VALUE) // true if strVar is the same as VALUE
e.g. VALUE = "aVaLue.TXT" or VALUE = "AVALUE.txt"
strVar.endsWith(VALUE) // true if strVar ends with a string equal to VALUE
e.g. VALUE = ".txt"
strVar.startsWith(VALUE) // true if strVar starts with a string equal to VALUE
e.g. VALUE = "AVa"
It is also possible to use methods such as "compareTo", "indexOf" and "lastIndexOF", but these produce a numeric or string result, not a boolean one (see Part Three -- Methods List for details). You can also try using "==" to compare strings, but the results are not reliable, because this test DOESN'T actually test the value of each string, but where the string variable points to.
Boolean Operators
Several conditions can be tested using the "&&", "||" and "!" operators, and placed within further parenthesis. e.g.
((userTest > 5) && (limitVal =0)) // true if userTest is over 5 AND limitVal is 0
((userTest > 5) || (limitVal =0)) // true if userTest is over 5 OR limitVal is 0
(userTest == 5) // true if userTest is equal to 5
!(userTest == 5) // true if userTest is NOT equal to 5
(userTest != 5) // true if userTest is NOT equal to 5
!(userTest != 5) // true if userTest is equal to 5!
!(strVal.equals("default") // true if strVal is NOT set to "default"
if
The if statement sets up a conditional block of code that gets used (IF) its conditions are met, with an optional block of code (ELSE). The formats are:
if (CONDITION1) CODEBLOCK; // if CONDITION1 is true, CODEBLOCK1 is executed
if (CONDITION1) // same as above, only nicer to look at
CODEBLOCK;
if (CONDITION1) // same as above
CODEBLOCK;
else
CODEBLOCKz; // if CONDITION1 is false, then CODEBLOCKz is executed
if (CONDITION1) // same as above
CODEBLOCK1;
else if (CONDITION2) // if CONDITION2 is true, CODEBLOCK2 is executed
CODEBLOCK2;
[else if (CONDITIONx) // if CONDITIONx is true, CODEBLOCKx is executed
CODEBLOCKx;]
else
CODEBLOCKz; // if none of the above conditions is true
CODEBLOCKz is executed.
Each CODEBLOCK can be either a single bit of code, or a series of coding statements surrounds by "{" and "}", e.g.
if (xPos>xLimit) { // Only do the first block of code if xPos > xLimit
xPos=0; // Reset xPos
yPos++; // Add 1 to yPos
} else {
x++; // Add 1 to xPos
cCount++; // Add 1 to cCount
}
switch and case
The SWITCH statement provides a way in which to test a value against a range of possibilities, as provided for by the CASE statements. Its form is:
switch (EXPRESSION) {
case CONSTANT1:
CODEBLOCK1;
[break;]
[case CONSTANTx:
CODEBLOCKx;]
[default:
CODEBLOCKz;]
}
The values for EXPRESSION should be either an integer, character or string. The value in EXPRESSION is checked against the value given in CONSTANT1, and if it matches, CODEBLOCK1 is executed. If not, extra cases (if present) are checked in the same way and their code is executed if the value of EXPRESSION equals their CONSTANT values. Finally, if none of the above was matched, CODEBLOCKz in the optional "default" condition is executed instead. Finally, a break statement (see below) can be used to prevent further processing of the SWITCH code. An example of a SWITCH block is...
switch (styleName) { // use String value from styleName variable
case "brown":
backgroundCol="brown"; // if styleName="brown", set backgroundCol to "brown"
case "grey":
backgroundCol="silver"; // if styleName="grey", set backgroundCol to "silver"
foregroundCol="black"; // also set foregroundCol to "black"
default:
backgroundCol="brown"; // if neither of the above is true, set it to "white"
}
You can "bunch" the CASE lines together to provide for multiple instances. e.g.
switch (styleName) { // use String value from styleName variable
case "brown":
case "pink":
case "red":
backgroundCol="brown"; // set if styleName is "brown", "pink" or "red"
case "grey":
case "monotone":
backgroundCol="silver"; // set if styleName is "grey", or "monotone"
foregroundCol="black";
default:
backgroundCol="brown"; // if neither of the above is true, set it to "white"
}
while
Like IF, a WHILE statement will execute a block of code if a condition is true. Unlike IF, it may repeat itself. After the block is executed, the condition is checked again, and if still true, the block is executed once again. This continues until either the condition becomes false, or a BREAK is used to stop the loop. the format is...
while (CONDITION) {
CODEBLOCK;
}
An example of this might be:
while ((xPos>0) && (xPos>xLimit)) { // true if 0 < xPos < xLimit
xStr= xStr+":"+toString(xPos); // adds "value" to xStr string variable
xPos=Math.random()*100)-50; // xPos = +/- 50
}
do while
This is similar to the WHILE statement, but the code block gets executed at least once, before the condition is checked, and any repeat executions are made. the format is...
do {
CODEBLOCK;
} while (CONDITION);
An example of this (based on the previous WHILE example) might be:
do (
xPos=Math.random()*100)-50; // xPos = +/- 50
xStr= xStr+":"+toString(xPos); // adds "value" to xStr string variable
while ((xPos>0) && (xPos>xLimit)) // true if 0 < xPos < xLimit
}
...which will always add the string version of xPos to xStr at least once (even if that value is OUTSIDE the limits set by the WHILE) at least once.
for
This statement runs a loop that will execute a code block a number of times, based on different values. The form is...
for (INITILIZER; CONDITION; INCREMENT) {
CODEBLOCK;
}
An example of this is...
<% // Produce links to all other pages, cooler than just next, previous links
for (int i=0; i<files.length; i++) {
Map vars = (Map)fileVariables.get(files[i]);
if (i+1 != imageNum) out.print("<a href=\"" + vars.get("currentPage") + "\">");
else out.print("<b>");
out.print(" " + (i+1));
if (i+1 != imageNum) out.print("</a>");
else out.print("</b>");
}
%>
...which is taken from the Help Pages. Here i is set to zero (pointing to the first character of an object) and incremented until all the files listed in the object are processed.
break
This is used to "break out of" a SWITCH, DO, WHILE or FOR statement block. There are two formats:
break; break LABEL;
The first format breaks the "innermost" loop (or SWITCH) that is running. If you don't insert a break into the code block, the following CASE conditions are still checked for after that CASE block is executed (and if you have changed the CONDITION value in that block, might get executed as well). The second format breaks any loops until the level at the label is found. e.g.
major_loop: for (int i=0; i<20; i++) {
for (int j=0; j<20; j++){
if (test=6)
break major_loop; // breaks both FOR loops if test = 6
test=Math.random()*6)+1; // test = between 1 to 6
result= i*j;
}
}
3. Methods
A method is a way of calling a special function which can produce a result from an input value. The following is a list if methods that can be used to modify and extract information from variables, and is divided into sections based upon the type of result you get (some of these are repeated in the other parts). This list is NOT complete, but refers to methods you would be most likely to use with jAlbum.
In the examples, "strVar", "cVar", and "numVar" are all sample variables, whereas "Character.", "String." and "Math." are literals. Anything called VALUE is a numeric value; INT is an integer number, CHAR is a character and STRING is a string value. Also, position 0 (zero) in a string variable is always the FIRST character of that variable.
Boolean
Character.isDigit(CHAR) // true if CHAR is a digit
Character.isLetter(CHAR) // true if CHAR is a letter
Character.isLetterorDigit(CHAR) // true if CHAR is a letter or digit
Character.isLowerCase(CHAR) // true if CHAR is in lower case
Character.isUpperCase(CHAR) // true if CHAR is in upper case
Character.isSpace(CHAR) // true if CHAR is the space character " "
strVar.equals(STRING) // true if strVar is the EXACTLY the same as STRING
including the case of each character
strVar.equalsIgnoreCase(STRING) // true if strVar is the same as STRING, but ignores
upper and lower case settings in the string
strVar.endsWith(STRING) // true if strVar ends with a string equal to STRING
strVar.startsWith(STRING) // true if strVar starts with a string equal to STRING
Numeric
Math.abs(VALUE) // returns the absolute value of VALUE
Math.max(VALUE1, VALUE2)// returns the maximum of the two values
Math.min(VALUE1, VALUE) // returns the minimum of the two values
Math.pow(VALUE1, VALUE2)// raises VALUE1 to the power of VALUE2
Math.sqrt(VALUE) // equals the square root of VALUE
Math.round(VALUE) // results in a rounding of VALUE to the nearest integer
Math.random() // equals a double precision number between 0 and 1. e.g.
compareTo(STRING1, STRING2) // compares two strings and gives either -1, 0, or +1,
based the alphabetical comparison of those strings.
strVar.indexOf(CHAR) // finds FIRST position of character CHAR in strVar.
returns -1 if not found
strVar.indexOf(CHAR, INT) // finds FIRST position of character CHAR in strVar
starting at position INT. returns -1 if not found
strVar.lastIndexOf(CHAR) // same as indexOf above, but finds LAST position
strVar.lastIndexOf(CHAR, INT) // in strVar of CHAR, starting from INT, if included
strVar.indexOf(STRING) // finds FIRST position of string STRING in strVar.
returns -1 if not found
strVar.indexOf(STRING, INT) // finds FIRST position of string STRING in strVar
starting at position INT. returns -1 if not found
strVar.lastIndexOf(STRING) // same as indexOf above, but finds LAST position
strVar.lastIndexOf(STRING, INT) // in strVar of STRING, starting from INT, if included
strVar.length() // results in length of string
Parsing
parseByte(strVal) // Converts strVal to a Byte parseInt(strVal) // Converts strVal to an Integer parseLong(strVal) // Converts strVal to a Long Floating Number
If you don't do this, you might get error messages when you try and do maths with a String! Sometimes it almost works, but "userVar1 + uservar2" is different when both values are Strings than when they're numbers (i.e. 4 + 5 = 9, but "4" + "5" = "45"!)
Character
Character.toLowerCase(CHAR) // lowercase value of CHAR Character.toUpperCase(CHAR) // uppercase value of CHAR strVar.charAt(INT)
String
String.toLowerCase(STRING) // lowercase value of STRING
String.toUpperCase(STRING) // uppercase value of STRING
String.valueOF(EXPRESSION) // returns the string value of VALUE,
where EXPRESSION is other than a string
itself (e.g. boolean or numeric).
strVar.replace(STRING1,STRING2) // replaces any occurrences of STRING1
in strVar with STRING2
strVar.substring(INT1) // returns a substring of strVar that starts at
position VALUE1 and ends at the end of
the string variable
strVar.substring(INT1,INT2) // returns a substring of strVar that starts at
position VALUE1 and ends at position VALUE2
strVar.trim() // removes all the whitespace from strVar
All user variables in jAlbum (the ones set on the Advanced tab) are all String variables. That means if you want to use them for maths, they have to be converted. The methods for this are:
4. Interfacing with jAlbum
Original code
Example one - Tables
Example two - Filters
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License