What are ResourceReferences in Wicket, and how do they work?

Question

I have seen examples containing things like this:

mountSharedResource("/images/logo.gif", new ResourceReference(ImageScope.class,
  "logo.gif").getSharedResourceKey());

mountSharedResource("/resource",
  Application.class.getName() + "/" + resourceKey);

But the Javadoc says this for the constructor:

ResourceReference(java.lang.Class<?> scope, java.lang.String name);

So when you create a ResourceReference, you give it a class. Why? Usually you would want either global scope or the scope of the ResourceReference object you have just created, no?

Also, what is name? Is it the sharedResourceKey? If not, where does the resourceKey come from? How is it generated, and why isn't it the name? Or is name looked up on the classpath, and magically loaded (assuming that there is only one file with that name on the classpath; what happens if there are multiple?)? If it does load a file with that name, why doesn't it say so in the Javadoc?

How do you actually assign a physcial resource to this ResourceReference? There is a getResource(), but they seem to have missed out setResource(). If you have, say, an image file in your webapp dir, how do you "attach" the reference to the file, its path, or even a byte stream of the file's contents? If there were a way to read resources in the webapp, this might be useful, but you can't; it's only in the classpath.

I would love to be able to "mount" the contents of, say, webapp/games/someGame.swf so that the SWF in a webapp can be accessed by the Wicket pages, or just get some kind of handle on them.

Answer 1

A resource such as an image is usually associated with a particular web page. So it makes sense to locate that image in the same place as the Java and HTML files.

The class parameter serves as a base from which to lookup your resource. The second parameter to the ResourceReference constructor is the name of the resource, relative to the directory containing the class.

So for example you could have -

new ResourceReference(AClass.class, "sub/directory/image.jpg");

You assign a physical resource by simply placing that resource in the correct directory when your application is deployed.

There's a chapter on using resources in the book "Wicket in Action".

Answer 2

To expand on Andrew's answer:

A ResourceReference per se is nothing but a reference to a resource available through SharedResources. Any kind of Resource that you add to SharedResources (usually done in your Application#init()) has a name that you define. Any Component that uses a resource can then refer to this shared resource through a ResourceReference with that name - hence the parameter being called "name". In this case the scope parameter (the class) is not needed.

This is the general case, to refer to any kind of Resource.

The case shown in your and Andrew's examples is a more special case: Your ResourceReference's name does not refer to a Resource previously added to SharedResources. Here a so-called PackageResource is lazily initialized and added to SharedResources.

PackageResource is what actually does the whole "load-file-from-classpath" stuff.

So if you want to just refer to a file like an image from your classpath, Andrew's example is simply a very useful shortcut to avoid creating that PackageResource yourself. As noted above, there is more to ResourceReference than just that :-)