Archive for 2010

September 19th, 2010
8:46 pm
Servlet Mapping Issues with Glassfish V3.0.1

Posted under Glassfish
Tags , , , ,

There seem to be some servlet mapping issues with Glassfish V3.0.1.

To summarize, the following outlines what the servlet mapping logic should do:-

  1. The <url-pattern> as below matches the input url and if there is a match, passes the url to the designated servlet (in this case the faces servlet).
  2. The url parts that match are stripped out, so that for extension mapping e.g. “*.jsf” pattern the “.jsf” is removed, and for path mapping e.g. “/faces/*” pattern the /faces subdirectory is removed.
  3. The javax.faces.DEFAULT_SUFFIX as below is applied to the result as a file type if one is not present, to give an actual file to be searched for. This is passed to the faces servlet for processing.

I tried the same combination in web.xml that I had used previously on Glassfish V2.1 with ICEfaces:-

<servlet-mapping>
<servlet-name>Faces Servlet</servlet-name>
<url-pattern>*.jsf</url-pattern>
</servlet-mapping>
<context-param>
<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
<param-value>.jsf</param-value>
</context-param>

The actual file type was also .jsf (index.jsf in this case)
This gave rise to the following intermittent error when run – it would run once or twice and then blow up:-

url:  http://localhost/PrimeTest1/index.jsf
error:  javax.servlet.ServletException: PWC1232: Exceeded maximum depth for nested request dispatches: 20

Changing the actual file type and the above javax.faces.DEFAULT_SUFFIX value to .xhtml worked correctly in every case.
This error occurred both with a simple Primefaces test page:-

<html xmlns=’http://www.w3c.org/1999/xhtml’
xmlns:f=’http://java.sun.com/jsf/core’
xmlns:h=’http://java.sun.com/jsf/html’
xmlns:p=’http://primefaces.prime.com.tr/ui’>
<h:head> </h:head>
<h:body>
<p:editor />
</h:body>
</html>

and also with a simple JSF page in a non Primefaces JSF 2 faceted eclipse web project:-

<html xmlns=”http://www.w3.org/1999/xhtml”>
<head>
<title>Test Page Title</title>
</head>
<body>
Test page body
</body>
</html>

It was therefore clear that the error was not Primefaces related, but appeared to be recursion caused by a servlet mapping issue. This post on the Glassfish Forums reported the issue – there was some discussion but no resolution, and I don’t think a bug has been raised.  This post also reported the same issue. Whilst I found a number of other posts too with what seemed like a related issue, there appeared to be no clear conclusion on any of them re the nature of the problem or a fix for it. I tried other combinations such as path mapping using “/faces/*” for the url pattern, “.jsf” for the default suffix, and “http://localhost/PrimeTest1/faces/index.jsf” for the url, but in this case the above error did not occur but a blank page was displayed. On examining the source for the page, it turned out to be the original page source i.e. it had not passed through the faces servlet.

My conclusion is that the servlet mapping/url pattern handling for Glassfish V3.0.1 has some issues, the precise nature of which is not clear. My solution is to use “.xhtml” for the actual filetypes and for the default suffix, and extension mapping using “*.jsf” for the url pattern – this combination works fine with no issues.

No Comments »

September 18th, 2010
11:08 am
Using display:inline-block and vertical-align in CSS

Posted under CSS
Tags , , , , , ,

Update 23/11/2010

Having experimented with this extensively on different browsers, I have found inconsistent results across browsers when trying to vertically centre a group of controls in a bordered div which closely surrounds them. If you need just a few pixels between the controls and the border, vertical centering does not work in a consistent browser independent manner. For larger centring, e.g. for centring a paragraph of text in a large div, the differences may not be noticeable, but at small scale they definitely are. For placing a close border around a group of related controls, my preferred method is now to use floats as detailed here. Note that the fact that floats are used does not force the rest of the document to use floats or to have non fixed sizing – the floats can be invisible to the outside due to a second outer non floated fixed size div. Also, the floated version works better when the contained controls are of variable or unknown size.

Original post

I originally used this here in order to centre the text on a Primefaces button, the usage of inline-block was incorrect.

What it does not do is allow you for example to centre a <span> element vertically and/or horizontally in a parent div!

What it does do is to allow setting of the alignment of an inline element relative to adjacent inline elements on a line (not relative to the parent container). It will therefore work within a <td> but not within a <div>

There appear to be a lot of fuzzy and partly incorrect articles on the net about this, and it was hard to find clear definitions. even the W3schools site does not greatly help, and does not appear to list for each element whether it is an inline or block element by default, which seems quite an omission.

In the end I found some helpful posts on it here and here which cleared it up for me, and explained why my simple example of a <span> in a <div> would not centre vertically with inline-block and vertical-align:middle!

Note regarding the use of vertical-align, a typical gotcha on this is if you have a horizontal group of buttons/combos and attempt to use top/bottom margins to try to centre them vertically, you may wonder why you do not get the expected behaviour as the margins do not appear to be properly honoured. This is a classic case for using display:inline-block and vertical-align:middle on all the controls.
Primefaces note:- the Primefaces commandButton components are set to  display:inline-block by Primefaces, using the internal jQuery ui-button class.

No Comments »

September 14th, 2010
3:17 pm
Adding Boot files to a Windows 7 System

Posted under Windows 7
Tags , , ,

Update 3/2/2012

One note to be aware of when doing this is that depending what other upgrades have been done, it may also be necessary to reset the boot order in the bios. Failure to do this may mean that the Windows boot manager on an old hard drive may still be presented at boot time even though bcdboot has run correctly as per the process below.

In my case, resetting the boot order solved the issue and boots were then done entirely from the SSD. I still had the option to boot from the other system by using the bios boot manager to pick the other hard drive to boot from.

 

Original Post

I needed to do this after installing Windows 7 64bit on an SSD, when I already had A Windows 7 installation on another HD.
I wanted the SSD to be the active partition/primary boot device – perhaps I should have made it the active partition in disk manager before installing but anyway I did not.

The install therefore kept the HD as the boot dev and installed a boot menu on it. The boot files were missing from the SSD. These can be added via the bcdboot  utility as follows :-

>bcdboot c:\windows /s c:

This had to be done from an elevated privilege command prompt (right click command prompt option or icon, run as administrator).

Microsoft information on bcdboot may be found here.

No Comments »

September 14th, 2010
1:55 pm
Startech/Silicon Image Drivers

Posted under Windows
Tags , ,

This situation is confusing as I now have 3 cards all using Silicon Image drivers.
Also, it appears to be notoriously difficult to find the drivers online – Silicon Image say that they are card vendor specific and don’t offer them. Re the unbadged card below from Tranquil, Tranquil do not offer any drivers for download, and therefore as it is unbadged and Silicon Image don’t offer any either, you are stuck if you lose the driver CD!

Do as follows :-
1/ Startech SATA Express PCI Express 2 port PEXESATA2
For Windows 7, Windows appears to find and install the correct driver, so I did not update it. It appears to be the same as the PEXESATA2 driver below.
Otherwise, use the PEXESATA2.zip driver. The “SATA Express_2Port” driver on the Silicon Image 3-ALL-34A drivers CD appears to be the same version so should work as well. This appears to be a non-RAID device. To allow safe device removal, also install HOTSWAP! for this device, as the driver does not enable windows safe removal. (32 or 64 bit version as appropriate). With the device connected, check the properties pages for both the disk device and the storage controller, and ensure that write caching is turned on.

2/ Startech 2 Port Cardbus eSATA – CBESAT2
Use the driver under “Startech 2 port Cardbus Card” – this folder contains a copy of the CD sent with the card. The driver required is under subdirectory:-
 NON-RAID\3512. This driver supports windows safe removal so you do not need to install HOTSWAP!. With the device connected to a disk, check the “Policies” tab on the device manager properties page for the disk, and check that ‘optimised for performance’ is selected to enable write caching.

3/ Tranquil unbadged 4 port PCI card.
This card appears to support RAID (although I don’t use it)
The driver used is the “SATA RAID_4Port” driver under the 3-ALL-34A driver CD
To allow safe device removal, also install HOTSWAP! for this device, as the driver does not enable windows safe removal. (32 or 64 bit version as appropriate). With the device connected, check the properties pages for both the disk device and the storage controller, and ensure that write caching is turned on. As I installed this a while back, I can’t recall if I had to change the setting manually after I installed the driver.

Note that the 3-ALL-34A driver CD seems to be a point upgrade on the 3-ALL-33A one. These CDs came with the “Startech SATA Express PCI Express 2 Port” card and the unbadged Tranquil “SATA RAID_4Port” card. I cannot remember which came with which, but using the later one in all cases should be correct.

No Comments »

July 29th, 2010
3:51 pm
Configuring SSDs for use under Windows XP

Posted under Windows XP
Tags , , ,

Update 7/10/2010

I had some further issues when trying to realign the boot partition of an OCZ Vertex 30GB SSD on an Intel D510 dual core atom ‘always on’ silent pc running Windows XP Pro.
I tried the technique used before below, using diskpar to create the partition and then using Acronis True Image 2010 to restore first the NTFS partition, then restoring the MBR and track 0 as a second subsequent operation. In order run diskpar standalone, I created a bootable CD containing diskpar using Bart PE, as I found that booting a Windows XP CD into recovery mode does not give you full command prompt capabilities – you cannot run an arbitrary .EXE utility at all (a real surprise to learn) – you can only use the commands listed. All this was done as below (see here) so as to force Acronis to re-use the partition created by diskpar. Unfortunately allthough the process went smoothly the resulting system would not boot, citing NTLDR/boot loader problems.

I then upgraded to Acronis True Image Home 2011 and also Acronis Disk Director 11, as these were both supposed to be SSD friendly and handle the alignment correctly. I deleted the partition and restored the original backup with the incorrect alignment, allowing Acronis to create the partition itself, and the system booted fine as before. I then used Disk Director to slightly shrink the partition to ensure that there was space to allow it to realign – there should have been a few MB on the end anyway, but I shrank it by 100MB to be really sure.

I then did a full standalone backup of the system disk with the shrunken partition. I found that just restoring that backup (shrunken but with the wrong alignment) with True Image 2011 was not enough – the incorrect alignment was still present on the SSD, i.e. it appeared that True Image always gives priority to the partition details in the backup. In hindsight it may have been possible to override the partition settings during the restore to cause Acronis to fix the alignment by using ‘new’ partition settings but I did not try – if so, this might have fixed the alignment problem in one go.

However, Disk Director 11 was able to delete and then recreate the partition correctly, i.e. when it created a new partition on the SSD it automatically used the correct alignment (1048576 bytes or 1MB), as confirmed afterwards by diskpar. I created a partition to fill the disk, as I knew that True Image would happily restore the slightly smaller shrunken one to a larger one. I then used the same technique as above with True Image Home 2011, i.e. restore the NTFS partition first without the MBR and track 0, then restore MBR and track 0 as a second operation after the restore.

This time, it all worked fine and I ended up with a bootable system with the correct partition alignment. I’m not sure what the issue was – perhaps the shrinking first fixed it. I do know that this technique has worked fine for me previously as below, when I backed up a 2.5" laptop hard drive via Acronis True Image, created an aligned partition on a new SSD with diskpar, and then restored the backup to the SSD with the same trick.

The resulting lessons learned seem to be as follows:-

  1. Use Disk Director 11 with SSDs, alignment will be correct, and you can easily do it standalone by creating a Disk Director boot CD.
  2. Using True Image 2011 is also recommended – it is stated to be SSD friendly and is better all around.
  3. However, care is needed when restoring an SSD backup with the wrong alignment, as by default even True Image 2011 keeps the wrong alignment. Either the technique above is needed or it may be possible to get Acronis to use ‘new’ partition settings to override the ones in the backup, in which case the restore can all be done in a single step.
  4. to be safe, when correcting wrong SSD alignment, shrink partition first by say a few 10s of MB to be sure (I used 100MB) to ensure there is no funny truncation when it is restored and realigned.

I have not done any performance comparisons before and after the realignment, but have confirmed that the alignment is now correct. Whilst I have seen posts on the internet that suggest lower alignment values than 1MB, both Windows 7 when it installs to an SSD, and Disk Director 11 use 1MB (1048576 bytes), so I am sticking with this value.

 

Original Post

Partition alignment is important for SSD performance to avoid unnecessary read/write cycles. Windows 7 appears to handle this but Windows XP does not. The partition alignment must be set manually when creating it (with diskpar or diskpart – diskpar seems to be preferred as it displays the partition offset in bytes so that the resulting offset can be accurately seen, even though diskpart is newer and has more features)

When restoring or cloning disks with Acronis True Image Home 2010, the original partition alignment is kept providing the operation does not recreate the partitions. See the Acronis forums here for details.

The OCZ forums have some articles on how to create correctly aligned partitions here and here.

Another step by step guide to cloning to an SSD with Acronis may be found here. When doing this, do not (as I did) forget the step which says to set the restore partition as primary and active in Acronis! In my case, Acronis made the wrong partition active so the SSD would not boot. It was simple enough to change – boot a system which can see the disk, then use disk management, right click the correct boot partition and select set as active. It is not necessary to repartition the SSD and re-restore the Acronis backup.

A good balanced article about optimising Windows XP for SSD use is here. There is a lot of misinformation around for example about the performance effects of swap files, which is based on misunderstandings about windows swap file usage, and also based on older SSDs with short service lives. The more informed wisdom appears to say that you should not disable the swap file as it will not make a significant difference.

No Comments »

June 11th, 2010
12:44 pm
Further notes on EJB Lookups

Posted under Glassfish
Tags , ,

Much of this has already been covered here, but I am posting these somewhat raw notes from an earlier investigative email as they include one or two links and points not covered elsewhere. I don’t have the time or inclination at present to rework everything into an existing post :-

 

1/ For local beans, you can just use defaults in @Stateless (in the bean) and in @EJB (in the referring code)
Note that when you do not use all the defaults, you must declare both the beaninterface and the name attributes

@EJB(name=”ejb/JPAGlassFishIce/SimpleBean”, beanInterface=SimpleBeanLocal.class)
private SimpleBean simpleBean;
2/ For remote beans, you can use e.g.

@Stateless(mappedName=”ejb/JPAGlassFishIceEJB/SimpleBean”)

Then

@EJB(beanInterface=SimpleBeanRemote.class, mappedName=”ejb/JPAGlassFishIceEJB/SimpleBean”)
private SimpleBean simpleBean;

Note – you must pass the class of the remote interface as above or it will not work, and you just get name not found exception.

3/ The above methods work for both access from one bean to another, and from a JSF managed bean to a remote (or local) bean
It also works from any POJO called from e.g. a JSF manged bean.
Note that this ability is container specific – Glassfish does it, other containers may vary in what/if/how they support.

4/ If doing JNDI lookups yourself to a local bean (via context.lookup), you need to add <ejb-local-ref> to web.xml as follows :-

 <ejb-local-ref>
    <ejb-ref-name>ejb/JPAGlassFishIce/SimpleBean</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <local-home></local-home>
    <local>uk.co.salientsoft.jpaglassfishice.domain.SimpleBeanLocal</local>
</ejb-local-ref>

This would be used if using e.g. Spring or a custom EL resolver  to inject references into JSF managed beans (via JSF DI)

Note that the JNDI name for the above local reference would be
“java:comp/env/ejb/JPAGlassFishIce/SimpleBean”
i.e. this is picking up from the <ejb-ref-name> above, and is prefixed java:comp/env
java:comp/env is a reference to the JNDI “Environment” service provider for Java EE
you can also use this  to look up environment variables etc.
see here http://java.sun.com/developer/technicalArticles/xml/WebAppDev4/

The <ejb-local-ref> stuff is done for you automatically if you use @EJB

5/ Note that JNDI names are container specific at present (fixed in java ee6)
See here for a good SUN post on all the EJB reference stuff :-
https://glassfish.dev.java.net/javaee5/ejb/EJB_FAQ.html

No Comments »

June 9th, 2010
5:06 pm
Centre text and other items e.g. on a Primefaces command button

Posted under HTML
Tags , , , , ,

Update

This post originally used display:inline-block and vertical-align:middle thinking mistakenly that these were part of the fix for the problem.
See here for a more complete understanding of it.
The modified CSS below works fine just by removing the padding and setting the font.

Taking the Primefaces commandButton as an example, the label is embedded in a span:-

<button attr1=value attr2=value…>
<span>Submit</span
</button>

The button has many attributes which are not relevant to this discussion.
However, as the span is an inline element, it does not have a top/bottom margin, width or height and using text-align:center; in css has no effect.

The default Primefaces button has fixed padding for the label, which works fine by default but which is a pain when you change the size of either the button or the text.

The following rules remove the padding and set the desired font correctly to centre the text for the Primefaces commnadButton:-

.ss-textbutton {
height:20px;
width:52px;
}
.ss-textbutton > .ui-button-text {
font-size:90%;
font-weight: bold;
padding:0px;
}

This CSS is activated when the class ss-textbutton is passed to the styleClass attribute of the commandButton tag.
This example declares a 52 x 20 button. It then targets the <span> within the button using ss-textbutton > ui-button-text, as the <span> in the commandButton has the ui-button-text class. It does the following to the <span>:-

  • sets a font size and weight
  • removes all the padding, so that the centring works correctly

In this example, I have deliberately not changed all buttons globally. The Primefaces documentation explains how to use the classes  ui-button, ui-button-text and ui-button-text-only to skin all buttons globally if this is desired.

This now allows us to resize our button, change the font size and the text, and still have the label nicely centred. We don’t have to mess around with tweaking the padding and other attributes in every case, which is a whole lot simpler and more modular.

No Comments »

May 28th, 2010
2:34 pm
Java Dev setup 2 – Eclipse Helios/Eclipselink/Primefaces/Glassfish V3

Posted under Java
Tags , , , , ,

This follows on from this post which detailed my previous development stack based on ICEfaces and Glassfish V2.1.

This new stack uses Primefaces, which I now prefer to ICEfaces, for the following reasons (in no particular order):-

  1. It has a JSF2 full release – ICEfaces is still only in Beta for JSF2 (as is richFaces)
  2. According to various reviews, it is simpler and more lightweight – this may also be a factor contributing to it being further ahead in JSF2 support.
  3. It has fuller functionality as standard – with ICEfaces you need to subscribe to the commercial paid version to get some enhanced features such as the treetable.
  4. Like ICEfaces, it has a very clean and modern look and feel out of the box with minimal effort. It comes with many themes out of the box, and new themes may be constructed easily online via themeroller, with minimal CSS knowledge. The Primefaces CSS is structured to global theme skinning CSS from component specific CSS.
  5. The transparent AJAX bridge of ICEfaces was a compelling feature, as it gave completely transparent partial rendering, although at the expense of resources/performance due to the need for a replica DOM tree in the server which had to be kept in synch. However the new AJAX features of JSF2 perform this in a new way which is also now standard.
  6. It has a related component library, Touchfaces, which supports webkit based mobile browsers – widely compatible mobile support will be an important requirement for me.

The following operations should be performed :-

  1. Download and install the chosen Java SE JDK
  2. Download and install Glassfish V3.0.1 (in my case, the Web profile edition,as it is lighter, I don’t need the full EE feature set and can upgrade incrementally as required). Eclipse has a plugin for, and therefore a dependency on, Glassfish so we do the latter first.
  3. Download and install Eclipse (in my case, Eclipse Helios for Java EE, which includes Java EE 6, Eclipselink and all the web tools.
  4. Install the Glassfish Plugin for Eclipse (note the updated workaround for Helios), then create a new server for it in Eclipse – right click in the server view then select new and follow the wizard instructions. Note that by default, Eclipse Helios appears to configure the default JVM using the separate JRE (installed by default by the JDK kit) rather than the JDK, even though the JDK was installed. The Glassfish adapter complains about this JRE as it needs a JDK based one. You can just add an additional one for the JDK, and point the server create wizard at it, as detailed here
  5. Download and install Primefaces and its documentation. Primefaces is installed manually – I just download the jar to e.g. <workspace>\libraries\primefaces-2.2M1. I then create it as a User Library as detailed here. If you open a web page with the Eclipse web page editor, and display the palette, you will find all the Primefaces components under the http://primefaces.prime.com/tr/ui pallet entry (there may be other palette entries with the name primefaces which may be empty, and should be ignored). Code/tag completion for the components should all work correctly.
  6. Download Tomcat if required. I use this for some projects that need a servlet container but not Java EE. I have in the past used the windows service installer version, which is a self installing .exe and installs/runs Tomcat as a service. However note that this does not work under Windows 64-bit if you are using a 32 bit JVM. See here for a manual install process from the zip kit to give you all the functionality of the windows installer version, including run as a service, configuration utility, and system tray monitor/utility.

Comments and issues when test driving the resulting installation:-

  • The new Glassfish V3 is fully OSGI compliant, as is Eclipse, so the old issues about Eclipse losing sync as to whether Glassfish was started or not are a thing of the past. However, Eclipse would not use the configured Glassfish admin username/password, and always asked for username and password on startup. It also gave the impression that Eclipse was occasionally losing sync and did not detect properly that Glassfish had already been started externally. This can be avoided by setting Glassfish to have a null password. When I did this, Eclipse never asked for credentials and always seemed to sync with it properly. As this was a dev workstation with no inbound external access and a dev/test install of Glassfish, I was quite happy to run it without a password.
  • I imported the Primefaces Component Showcase .war file directly into Eclipse as a test to play around with. This ran fine, but initially any changes to the Java code did not deploy to Glassfish. It turned out that the code folders as loaded were not under the src folder where Eclipse was expecting them, so the auto build process was not compiling them. I just moved all the source up to where Eclipse was expecting them – it already had a set of empty packages there so I just dragged all the source files in the project explorer from where it originally was into the appropriate matching empty packages and all was well. Eclipse then compiled and deployed any Java changes I made correctly.
  • Glassfish 3 is supposed to start much faster than 2.1, it did not feel much faster but I did not do any testing on this. However, the new hot deployment on Glassfish 3 was good. I made some simple changes with the Primefaces component showcase, saved them and then did a republish. Some changes e.g. to xhtml files deployed almost instantly. Some java code changes that had larger scale impact took several seconds but were still hot deployed successfully. With Glassfish 2.1, I had found that the integration with Eclipse was a bit hit and miss – sometimes changes would hot deploy, but quite often things just got a bit sick/out of sync as already stated and Glassfish would need restarting, which was always the slow thing. This is why in the end I stuck with Tomcat for dev testing etc. as even though code changes triggered a restart, the start time was so much faster. I’m hoping for better things with Glassfish V3 and the reports I have seen are positive but will need to try it in anger for a while.

No Comments »

May 26th, 2010
9:35 pm
Notes on Using CDI/Weld

Posted under Java
Tags , , , ,

CDI stands for Context and Dependency Injection, and is the standard for Java EE 6, being an important part of the Java EE 6 stack. The reference implementation of CDI is JBoss Weld. Full details including documentation downloads for Weld, may be found here.

Here are some initial pointers/gotchas when starting out with CDI:-

  • Any bean which is @SessionScoped or @ConversationScoped must be serializable. If you do not obey this rule you get an error when trying to deploy your application. The easiest way to do this in Eclipse is to implement Serializable. This will give a warning about the need to declare serialVersionUID.Just right click the warning and pick quick fix. You will have the choice of a default serialVersionUID or a generated one. Normally you would want to use a generated one, which Eclipse will do automatically for you when you pick the option. (You can also use a Java command line tool to do it but there is no point as Eclipse is easier). This post here gives more details about SerialVersionUID and serialization.
  • Any bean which uses parameterised types (i.e. generics) in its interface must be declared as @Dependent, i.e. it is only used and referenced from one client bean and its lifetime is dependent on the lifetime of that client bean – it is created when the client bean is created, and destroyed when it is destroyed. If you do not obey this rule you get an error when trying to deploy your application. An example of this situation might be a generic table bean which returns a list of rows of a generic type <E>, e.g. @Dependent public class TableBean<E> implements Serializable. This makes sense if you think about it – if it returns a generic type, it cannot be instantiated in isolation as it is the creating client which determines the actual type returned. Remember in this regard that CDI performs type safe injection in order to pick up as many errors as possible at compile time. Therefore, taking an example of our table bean, a consequence of this is that the table bean cannot be referred to directly from a JSF page. This is not the issue that it might appear. In practice, the table bean will be created by a client backing bean for the page. For example, a UserCredentials.jsf page might contain several tables, each backed by a different TableBean. The page will have its own backing bean, for example UserCredentialsBean, which will hold the backing state for the whole page. When referring to a table on the JSF page, it will always be referred to via the page backing bean, for example userCredentials.rightTable.rows. This is what you would naturally do anyway, and referring to the dependent bean via a property of its ‘owning’ parent if perfectly correct and does not violate any CDI rules. Note that it is also perfectly correct to assign such a reference to a JSF table value attribute for use in the table, and to then use the shorthand name assigned to the var attribute to refer to the bean. This is also fine and does not break any rules.
  • When referencing an EJB from a JSF backing bean, you should always use CDI annotations rather than the older @EJB ones, as the CDI ones are typesafe and allow all the additional flexibility of CDI, such as alternatives for swapping in mock test versions of EJBs by adding settings in beans.xml. An example of injecting a local EJB into a backing bean might be  private @Inject SentryServiceLocal sentryService; assuming that SentryServiceLocal is the local interface for the EJB.
  • Given the choice, you should always use CDI for preference rather than a legacy feature. For example, JSF managed beans are still available for backwards compatibility in JSF (and even have some new features for JSF 2.0). However, you should ignore these and use CDI instead as it offers superior flexibility and type safety. Using CDI across the board gives additional benefits such as when grouping annotations using Stereotypes.

No Comments »

May 14th, 2010
6:45 pm
Javadoc creation and formatting

Posted under Java
Tags , , , ,

Some tips and gotchas on this, as follows :-

1/ the Oracle documentation pages for Javadoc complete with examples etc. may be found here

2/ An example of Javadoc applied to a project may be found in the PropertyTree project in the repository.

3/ JAutodoc is a useful Eclipse plugin. Whilst Eclipse can generate Javadoc comments at source creation time if you tick the box for it, and lets you add them afterwards one by one via ctrl/alt/J etc., using  JAutodoc allows creation, addition or replacement of a full set of Javadoc comments to an entire project at any time. It also has a better stab at guessing comments for properties etc. than Eclipse, by parsing words out of the code. Obviously there is still a lot of manual editing to be done, but I found it a useful addition. Note that JAutodoc is available for a project on the package Explorer context menu for a project, but not on the project explorer one.

4/ Package level documentation sits in package.html in the package source directory. As Javadoc is frames based, the following doctype is recommended by Oracle for this file :- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">. Simple html is the order of the day as Javadoc has simple, somewhat retro styling. You can get new style sheets for it to spice it up, but I find the standard ones perfectly readable. Javadoc has its own Stylesheet.css, but I avoided amending this, and deliberately did not add another stylesheet of my own. Therefore, I avoided heavy use of styling, and just borrowed the odd style from the built in stylesheet for my own uses such as table header styling below.

5/ For subheadings in the package doc <h3> and <h4> worked fine.

6/ It was straightforward to add simple tables. Whilst some of the attributes are rather outdated/deprecated in favour of CSS, they are also used elsewhere in the Javadoc for its own tables, so I did not lose sleep over it. I used the TableHeadingColor class from Javadoc’s own stylesheet to give a similar background colour to my own table headers.

<table border="1" cellspacing="1" width="100%">
    <tr class="TableHeadingColor">
        <th>Column 1 Header</th>
        <th>Column 2 Header</th>
    </tr>
    <tr>
        <td>Column 1 data</td>
        <td>Column 1 data</td>
    </tr>
</table>

7/ Styling code samples is a bit messy with several tags being involved. This post here on StackOverflow discusses some of the issues In the end I used the following examples, generally going with what worked well:-

<blockquote><pre>
      PropertyTree propertyTree = new PropertyTree("lan").load("Test.properties");
</pre></blockquote>

or :-

<blockquote><pre>{@code
lan.default.broadcast=10.0.0.255
lan.default.port=7

}</pre></blockquote>

The code tag (“{@code …}” was supposed to be the one to use here (particularly when Generics are involved) but was a bit mixed in its usefulness, and I found some variations in the tabbing, and closing braces in the code can be an issue as the code tag also uses this for its own closure. I did not therefore always use it. Interestingly the above StackOverflow post cites that String.java in the JRE just uses <p><blockquote><pre>,  so I often followed suit.

8/ Individual code or data identifiers such as class and method names looked good in a fixed font when framed with <code></code>, which seemed to be the preferred way to highlight them. Sometimes I made them links as follows, but I did not do this all the time when there was already a link on the comment, as it was tedious and unnecessary. Links can be added, and you can link to a method, a class or a package (which links to package.html) by just linking to the desired level. The first parameter after {@link is the hyperlink, and the second parameter is the clickable description that appears for the hyperlink. Eclipse does code completion for the tags when you are entering them. The following example links to a property (which is specified after the “#”):-

{@link  uk.co.salientsoft.util.propertytree.TagTree#getProperty() TagTree.getProperty()}

9/ One gotcha is that for overriden methods, the Javadoc always comes from the inherited method, and the Javadoc method comments in the subclass are ignored. However, you can add additional comments by using the Javadoc documentation comment syntax (prefixed “/**” i.e. with the extra asterisk on the first line) in the subclass, and these will be added in and not ignored:-

/**
  * For the <code>NullIterator</code> this will always return <code>false</code>.
  */

10/ In Eclipse, you can create Javadoc via the Project/Create Javadoc menu bar option (this is not available on the package explorer context menu). There are a number of options when doing so, but these are not all defaulted to your previous settings when you go back next time round. You can therefore create and save an Ant build file for the Javadoc which you can then re-run much more easily. Javadoc.exe needs to be on the path for this – it should be anyway if you have Java SE installed and on the path, and for me I did not have to add it. You can then open the Ant view in Eclipse. In the view pane, right click and select Add Buildfiles… and browse for the Ant build file which you saved at Javadoc creation time. This then stays pinned to the Ant pane and you can double click it any time to recreate your Javadoc with all the saved settings.

No Comments »