Appendix A - Java Language
This chapter explains some of the key Java Language features that are used in Carousel. It is intended to highlight the impact of these features on Carousel rather than being a tutorial or programmer's guide for the language itself.
Don't forget you can use Java
It may seem a little obvious but it can be easy to forget: Carousel is a Java based system. The objects created by Carousel are all Java objects and you can interact with them using the normal Java programming idioms.
The upshot of this is that you are not constrained to use what is in the Carousel framework. If something is missing or does not suit your purposes then you can just code it in Java.
For example Carousel provides numerous ways of adding components but sometimes you may have special needs and these needs may not suit the Carousel programming idioms. Instead of using saying the component registry or the component factories you can just add the component you need in the page's constructor or in the pageCreated method.
Object types
Java is a strongly typed language but to a certain extent the loose coupling and late binding promoted by the XUI and Carousel frameworks can hide this facet of the language. However the framework is primarily a Java based system and ultimately the language's type system will come to play.
This hiding of information may in some circumstances limit the amount of compile time checking carried out by the compiler when building a Carousel application. For this reason it is recommended that you use the debug version of the XUI libraries when developing an application. These libraries output a lot of useful debug and diagnostic information and this information can help you track down numerous problems, not just type issues.
As XUI is an open source language you can also obtain the source code and include it in your project so that you can gain even more information about the cause of a particular problem.
If for instance you use the model to pass data between components of your application you may at first be unaware of type issues as the data model is to some extents agnostic about data types. However your application's components will probably require a specific type and if this type is not what was stored in the model you may get type conversion exceptions.
As the chain of events that leads to such situations may be many layers deep you will probably want all the debug information you can get. In the release builds the XUI framework will suppress some error messages and so all you would see would be a message saying that there was a failure invoking a method, with the debug version you should be able to pin-point the source of the error.
Also, with a system comprised of many loosely coupled files you can also get the above types of problems if the wrong type of data has been mapped into the application, but of course this sort of problem is not unique to XUI. Again the debug versions of the libraries can be helpful and with Carousel you also get configuration and visualization tools that may help prevent such problems arising in the first place.
Returning to the subject of types, the framework provides the IntegerAdapter and DoubleAdapter classes to make it a little easier to work with the model when using integer and double values. The same techniques used in these classes can just as easily be applied to other types. The adapters simplify access to objects of either Integer or Double within the model and make it less likely that you will forget to make a necessary type conversion. The adapters also have the nice fringe benefit of making the code a little easier to read.
Inheritance
Inheritance is one of the cornerstones of object oriented languages such as Java. One aspect of inheritance is information hiding and this is something that you should be aware of when programming a Carousel application. The framework does a lot of work on your behalf and sometimes it is easy to forget this.
One of the most common ommissions is the use of the properties of the base class for pages, XPage . The XPage class contains several references to key objects like the project manager, the style manager and the project. Remembering to use these variables in your code can save a lot of work.
You should also remember that inheritance may be several levels deep, so don't just stop looking for what you need one level down.
Inheritance also works the other way round too and you can extend many of the features in the XUI framework. Many of the features of the framework are designed with this in mind and are intended to allow you plug-in variations of the default structures and mechanisms.
Package Names
The package name in a Java application should correspond to a directory or folder in the operating system. In Carousel this directory must also be a child of the project's source directory.
Special consideration should be given to package naming for cross platform applications and it is worth noting that the file and directory naming conventions vary from operating system to operating system.
In particular Windows users should note that unlike most operating systems Windows is not case sensitive. Furthermore Java is case sensitive so when the JVM loads resources such as images and other files the case of the path and file name is important.
When testing within the development environment under a platform such as Windows it is possible that a file can be loaded even if the case is incorrect as the operting system will ignore such details. However once the application is distributed and when loading from a Jar file the JVM will expect the case to match exactly.
When applied to package names this logic means that the directory names must match the segments of the package name exactly. Windows users should also be aware that Windows Explorer can capitalize the folder names so what is displayed by explorer may not match the actual filename exactly.
Here's what the Java Language Specification has to say about packages:
Programs are organized as sets of packages. Each package has its own set of names for types, which helps to prevent name conflicts. A top level type is accessible (§6.6) outside the package that declares it only if the type is declared public.
The naming structure for packages is hierarchical (§7.1). The members of a package are class and interface types (§7.6), which are declared in compilation units of the package, and subpackages, which may contain compilation units and subpackages of their own.
A package can be stored in a file system (§7.2.1) or in a database (§7.2.2). Packages that are stored in a file system have certain constraints on the organization of their compilation units to allow a simple implementation to find classes easily.
A package consists of a number of compilation units (§7.3). A compilation unit automatically has access to all types declared in its package and also automatically imports all of the public types declared in the predefined package java.lang.
For small programs and casual development, a package can be unnamed (§7.4.2) or have a simple name, but if code is to be widely distributed, unique package names should be chosen (§7.7). This can prevent the conflicts that would otherwise occur if two development groups happened to pick the same package name and these packages were later to be used in a single program.
|
Classloaders
Carousel makes extensive use of classloaders both within the editor and at runtime. Carousel even includes a custom classloader so that you can access resources from the standard Carousel folders (pages, resources, classes and lang) without having to include those folder names in the file path.
The classloader infrastructure comes into play whenever you need to load files, classes or other resources. Ultimately the system classloader is used and loads files from the classpath. The impact of this is most apparent if you wish to load third party classes. The classes may be found at design time within Carousel as Carousel will load extra Jar files in some cases, like for example when components are registered. However at runtime you may have to explicitly alter your classpath by adding references to such Jar files.
Carousel may also help you by packaging the classes you use into a Jar file but you may be well advised to review what is included in the Jars so that you can get a more optimal distribution.
Classloading also affects the way in which you use resources. At runtime, once your files are packaged into the Jar files they will be read-only and the paths to the files will be case-sensitive. On a Windows system where the paths and filenames are normally not case sensitive this can represent a significant testing issue, so be advised that you should try and respect the case of paths and filenames at all times.
Reflection
Reflection plays an important role in Carousel. Many of the links between you application code and the framework are made via relfection. It may be worth taking a look at the reflection API to see how in works in practice. Notably Carousel event handling (see "Event handling" on page 147 ) and dynamic attributes (see "Evaluated attributes and helpers" on page 223 ) are invoked via reflection.
Encodings
Encoding is sometimes an issue for Carousel and for Java applications. Carousel is affected by encodings when working with localized text (see "Localization" on page 187 ), or indeed for any text file resource that the framework loads.
Encodings also come into play when working with client-server systems. Data transmitted over the network will need to be properly encoded so that the data can be correctly decoded on the server side. This encoding of data is also an issue for simple posting of data and Carousel includes a service for URL encoding and decoding data.
Even if data is not being transmitted over a network URLs are commonly used and you should be aware of the requirements for encoding URLs. The services provided by Java and Carousel make it relatively easy to solve encoding problems so long as you are aware of the issues.
Again, the interaction with the Windows operating system may be the source of confusion as the operating systems constraints on filenames do not match the specification for URLs and if the two are mixed you may well not notice any problems, that is until the naming conditions are broken. Typically this may occur when selecting a path or file name and passing it as a URL.
Learning Java
For those of you new to the Java programming language here are some resources that may be useful in learning the Java Programming language. Many more resources can be found by searching the Internet and the many Java related websites..
Table A-1 - Java learning resources
|
|
|
|
Java Coffee Break
http://www.javacoffeebreak.com/
Never programmed in Java before? Not sure where to start? This quick tutorial will get you up to speed. You'll learn how to compile and run simple Java applications
|
|
|
|
|
Introduction to Programming Using Java
http://math.hws.edu/javanotes/
Introduction to Programming Using Java, the fourth edition of a free, on-line textbook on introductory programming, which uses Java as the language of instruction.
|
Further Resources
Sun's Javasoft website has extensive information about using an learning Java. A good place to start is the New to Java Center :
http://java.sun.com/learning/new2java/index.html
If you were logged in you could rate this article or add a comment.
