http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc new file mode 100644 index 0000000..4b9c6c6 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_14.adoc @@ -0,0 +1,76 @@ + + + +Introduced in Wicket 6.20.0 / Wicket 7.0.0 there is a default way to be used in which the output of all CssHeaderItems / JavaScriptHeaderItems is modified before they are cached and delivered to the client. You can add a so called Compressor by receiving the resource settings and invoke 1.setJavaScriptCompressor(...) / 1.setJavaScriptCompressor(...). If you want to add several Compressors use _org.apache.wicket.resource.CompositeCssCompressor_ or _org.apache.wicket.resource.CompositeJavaScriptCompressor_ + +*Java Code:* +[source,java] +---- +... +Â Â Â public class WicketApplication extends WebApplication +Â Â Â { +Â Â Â Â Â Â @Override +Â Â Â Â Â Â public Class<? extends WebPage> getHomePage() +Â Â Â Â Â Â { +Â Â Â Â Â Â Â Â Â return HomePage.class; +Â Â Â Â Â Â } +Â Â Â +Â Â Â Â Â Â @Override +Â Â Â Â Â Â public void init() +Â Â Â Â Â Â { +Â Â Â Â Â Â Â Â Â super.init(); +Â Â Â Â Â Â Â Â Â getResourceSettings().setCssCompressor(new CssUrlReplacer()); +Â Â Â Â Â Â } +Â Â Â } +... +---- + +In the previous example you see that a _org.apache.wicket.resource.CssUrlReplacer_ is added which does not compress the content, but replaces all urls in CSS files and applies a Wicket representation for them by automatically wrapping them into PackageResourceReferences. Here is an example where you can see what Wicket does with the url representation. + +HomePage (in package my/company/): +*Java Code:* +[source,java] +---- +... +response.render(CssReferenceHeaderItem.forReference(new PackageResourceReference(HomePage.class, "res/css/mycss.css"))); +... +---- + +mycss.css (in package my/company/res/css/): +*CSS:* +[source,java] +---- +... +body{ +Â Â Â background-image:url('../images/some.png'); +} +... +---- + +some.png (in package my/company/res/images/): +<blob> + +Output of mycss.css: +*CSS:* +[source,java] +---- +... +body{ +Â Â Â background-image:url('../images/some-ver-1425904170000.png'); +} +... +---- + +If you add a url which looks like this background-image:url('../images/some.png?embedBase64'); Wicket is going to embed the complete image as base64 string with its corresponding mime type into the css file. It looks like the following code block demonstrates. + +Output of mycss.css: +*CSS:* +[source,java] +---- +... +body{ +Â Â Â background-image: url(data:image/png;base64,R0lGODlh1wATAX....); +} +... +---- +
http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc new file mode 100644 index 0000000..320890e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_15.adoc @@ -0,0 +1,67 @@ + +The FileSystemResourceRenference comes along with the FileSystemResource, FileSystemResourceStreamReference and the FileSystemResourceStream. Those classes provide a simple way to handle resources with Java's NIO API in Wicket starting from JDK version 7.0. (Available since Wicket 7.2.0 / Wicket 8.0.0) + +Example: To include a resource which is zipped into a file and located in a specific folder in the file system you can simply write code like this: + +Java: +[source,java] +---- +URI uri = URI.create("jar:file:///videosFolder/videos.zip!/folderInZip/Video.mp4"); +Path path = FileSystemResourceReference.getPath(uri); +FileSystemResourceReference ref = new FileSystemResourceReference("video",path); +Video video = new Video("video",ref); +add(vide); +---- + +HTML: +[source,java] +---- +<video wicket:id="video"/> +---- + +Using FileSystemResourceReference mounted: + +Java: +[source,java] +---- +mountResource("/filecontent/${name}", new FileSystemResourceReference("filesystem") +{ + private static final long serialVersionUID = 1L; + + @Override + public IResource getResource() + { + return new FileSystemResource() + { + private static final long serialVersionUID = 1L; + + protected ResourceResponse newResourceResponse(Attributes attributes) + { + try + { + String name = attributes.getParameters().get("name").toString(""); + URI uri = URI.create( + "jar:file:////folder/example.zip!/zipfolder/" + name); + return createResourceResponse( + FileSystemResourceReference.getPath(uri)); + } + catch (IOException | URISyntaxException e) + { + throw new WicketRuntimeException("Error while reading the file.", e); + } + }; + }; + } +}); +---- + +FileSystemResourceReference.getPath(uri) uses a FileSystemPathService to setup a path the resource reference can work on. + +So if you write a custom file system you can easily handle every path by adding a *org.apache.wicket.resource.FileSystemPathService* text file into *META-INF/services* and put in your implementation. + +A reference implementation can be found in the java class org.apache.wicket.resource.FileSystemJarPathService. + +Further FileSystemProviders and the corresponding FileSystems can be implemented as described here: + +http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html[http://docs.oracle.com/javase/7/docs/technotes/guides/io/fsp/filesystemprovider.html] + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc new file mode 100644 index 0000000..1fc8173 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_16.adoc @@ -0,0 +1,23 @@ + +Another way to receive external image resources is to use the corresponding component with a model which contains the target URL. + +The ExternalImage and ExternalSource components which are available since Wicket 7.2.0 / Wicket 8.0.0 fulfill that task. + +The following example demonstrates the usage of a CompoundPropertyModel with the model object [ImageSrc] The model object, bound to surrounding component / page, contains an attribute named [url] which is read by the component: + +Java: +[source,java] +---- +ImageSrc imageSrc = new ImageSrc(); +imageSrc.setUrl("http://www.google.de/test.jpg";); +setDefaultModel(new CompoundPropertyModel<>(imageSrc)); +add(new ExternalImage("url")); +---- + +HTML: +[source,java] +---- +<img wicket:id="url" /> +---- + +The ExternalImage can also be constructed by passing in a Model (src) and Model of List (srcSet). For ExternalSource only the srcSet is available. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc new file mode 100644 index 0000000..72c0dc3 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_17.adoc @@ -0,0 +1,8 @@ + + + +In this chapter we have learnt how to manage resources with the built-in mechanism provided by Wicket. With this mechanism we handle resources from Java code and Wicket will automatically take care of generating a valid URL for them. We have also seen how resources can be bundled as package resources with a component that depends on them to make it self-contained. + +Then, in the second part of the chapter, we have built a custom resource and we have learnt how to mount it to an arbitrary URL and how to make it globally available as shared resource. + +Finally, in the last part of the paragraph we took a peek at the mechanism provided by the framework to customize the locations where the resource-lookup algorithm searches for resources. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc new file mode 100644 index 0000000..fd61770 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_2.adoc @@ -0,0 +1,4 @@ + + + +Most of the times in Wicket we won't directly instantiate a resource but rather we will use a reference to it. Resource references are represented by abstract class _org.apache.wicket.request.resource.ResourceReference_ which returns a concrete resource with factory method getResource(). In this way we can lazy-initialize resources loading them only the first time they are requested. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc new file mode 100644 index 0000000..cc1b6ed --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_3.adoc @@ -0,0 +1,180 @@ + + + +With HTML we use to include static resources in our pages using tags like <script>, <link> or <img>. This is what we have done so far writing our custom panels and pages. However, when we work with a component-oriented framework like Wicket, this classic approach becomes inadequate because it makes custom components hardly reusable. This happens when a component depends on a big number of resources. In such a case, if somebody wanted to use our custom component in his application, he would be forced to know which resources it depends on and make them available. + +To solve this problem Wicket allows us to place static resource files into component package (like we do with markup and properties files) and load them from component code. + +These kinds of resources are called package resources (a CSS and a JavaScript file in this screenshot): + +image::../img/package-resources.png[] + +With package resources custom components become independent and self-contained and client code can use them without worrying about their dependencies. + +To load package resources Wicket provides class _org.apache.wicket.request.resource.PackageResourceReference_. + +To identify a package resource we need to specify a class inside the target package and the name of the desired resource (most of the times this will be a file name). + +In the following example taken from project ImageAsPackageRes, CustomPanel loads a picture file available as package resource and it displays it in a <img> tag using the built-in component _org.apache.wicket.markup.html.image.Image_: + +*HTML:* +[source,html] +---- +<html> +<head>...</head> +<body> +<wicket:panel> + Package resource image: <img wicket:id="packageResPicture"/> +</wicket:panel> +</body> +</html> +---- + +*Jave Code:* +[source,java] +---- +public class CustomPanel extends Panel { + + public CustomPanel(String id) { + super(id); + PackageResourceReference resourceReference = + new PackageResourceReference(getClass(), "calendar.jpg"); + add(new Image("packageResPicture", resourceReference)); + } +} +---- + +Wicket will take care of generating a valid URL for file calendar.jpg. URLs for package resources have the following structure: + +_<path to application root>/wicket/resource/<fully qualified classname>/<resource file name>-<ver-<id>>(.file extension)_ + +In our example the URL for our picture file calendar.jpg is the following: + +_./wicket/resource/org.wicketTutorial.CustomPanel/calendar-ver-1297887542000.jpg_ + +The first part of the URL is the relative path to the application root. In our example our page is already at the application's root so we have only a single-dotted segment. The next two segments, wicket and resource, are respectively the namespace and the identifier for resources seen in <<urls.adoc#_generating_structured_and_clear_urls,paragraph 10.6.4>>. + +The fourth segment is the fully qualified name of the class used to locate the resource and it is the scope of the package resource. In the last segment of the URL we can find the name of the resource (the file name). + +As you can see Wicket has automatically appended to the file name a version identifier (ver-1297887542000). When Wicket runs in DEVELOPMENT mode this identifier contains the timestamp in millisecond indicating the last time the resource file was modified. This can be useful when we are developing our application and resource files are frequently modified. Appending the timestamp to the original name we are sure that our browser will use always the last version of the file and not an old, out of date, cached version. + +When instead Wicket is running in DEPLOYMENT mode, the version identifier will contain the MD5 digest of the file instead of the timestamp. The digest is computed only the first time the resource is requested. This perfectly makes sense as static resources don't change so often when our application runs into production environment and when this appends the application is redeployed. + +NOTE: Package resources can be localized following the same rules seen for resource bundles and markup files: + +image::../img/package-resource-localization.png[] + +In the example illustrated in the picture above, if we try to retrieve package resource calendar.jpg when the current locale is set to French, the actual file returned will be calendar_fr.jpg. + +=== Responsive images - multiple resource references use in one component + +Since Wicket 7.0.0 the build-in component _org.apache.wicket.markup.html.image.Image_ allows you to add several ResourceReferences via varargs and to provide sizes for each image so that the browser is able to pick the best image source. + +*HTML:* +[source,html] +---- +... + Package resource image: <img wicket:id="packageResPicture"/> +... +---- + +*Java Code:* +[source,java] +---- +... + Image image = new Image("packageResPicture", + new PackageResourceReference(getClass(),"small.jpg"), + new PackageResourceReference(getClass(), "large.jpg"), + new PackageResourceReference(getClass(), "medium.jpg"), + new PackageResourceReference(getClass(), "small.jpg")); + image.setXValues("1024w", "640w", "320w"); + image.setSizes("(min-width: 36em) 33.3vw", "100vw"); + + this.add(image); +... +---- + +The component _org.apache.wicket.markup.html.image.Picture_ is used to provide a fallback image _org.apache.wicket.markup.html.image.Image_ and several source components _org.apache.wicket.markup.html.image.Source_ which gives a developer the control as to when and if those images are presented to the user. + +*HTML:* +[source,html] +---- +... + <picture wicket:id="picture"> + <source wicket:id="big" /> + <source wicket:id="small" /> + <img wicket:id="fallback" /> + </picture> +... +---- + +*Java Code:* +[source,java] +---- +... + Picture picture = new Picture("picture"); + + Source big = new Source("big", new PackageResourceReference(getClass(), "big.jpg"), new PackageResourceReference(getClass(), "big-hd.jpg"); + big.setXValues("1x","2x"); + big.setMedia("(min-width: 40em)"); + picture.add(big); + + Source small = new Source("small", new PackageResourceReference(getClass(), "small.jpg"), new PackageResourceReference(getClass(), "small-hd.jpg"); + small.setXValues("1x","2x"); + picture.add(small); + + Image image = new Image("fallback", new PackageResourceReference(getClass(), "fallback.jpg")); + picture.add(image); + + this.add(picture); +... +---- + +=== Inline Image - embedded resource reference content + +In some components like in the inline image resource references are going to be translated to other representations like base64 content. + +*Java Code:* +[source,java] +---- +... + add(new InlineImage("inline", new PackageResourceReference(getClass(),"image2.gif"))); +... +---- + + +=== Media tags - resource references with content range support + +Since Wicket 7.0.0 the PackageResource and the PackageResourceReference support [Range] HTTP header for the request and [Content-Range] / [Accept-Range] HTTP headers for the response, which are used for videos / audio tags. The [Range] header allows the client to only request a specific byte range of the resource. The server provides the [Content-Range] and tells the client which bytes are going to be send. + +If you want the resource not to be load into memory apply readBuffered(false) - this way the stream is written directly to the response. (_org.apache.wicket.resource.ITextResourceCompressor_ will not be applied if readBuffered is set to false) + +*HTML:* +[source,html] +---- +... + <video wicket:id="video" /> +... +---- + +*Java Code:* +[source,java] +---- +... + Video video = new Video("video", new PackageResourceReference(getClass(),"video.mp4").readBuffered(false)); +... +---- + +=== Using package resources with tag <wicket:link> + +In <<urls.adoc#_automatically_creating_bookmarkable_links_with_tag_wicketlink,paragraph 10.3>> we have used tag <wicket:link> to automatically create links to bookmarkable pages. The same technique can be used also for package resources in order to use them directly from markup file. Let's assume for example that we have a picture file called icon.png placed in the same package of the current page. Under these conditions we can display the picture file using the following markup fragment: + +[source,html] +---- +<wicket:link> + <img src="icon.png"/> +</wicket:link> +---- + +In the example above Wicket will populate the attribute src with the URL corresponding to the package resource icon.png. <wicket:link> supports also tag <link> for CSS files and tag <script> for JavaScript files. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc new file mode 100644 index 0000000..59ae47e --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_4.adoc @@ -0,0 +1,35 @@ + + + +Wicket comes with interface _org.apache.wicket.markup.html.IHeaderContributor_ which allows components and behaviors (which will be introduced later in <<advanced.adoc#_enriching_components_with_behaviors,paragraph 18.1>>) to contribute to the header section of their page. The only method defined in this interface is _renderHead(IHeaderResponse response)_ where _IHeaderResponse_ is an interface which defines method _render(HeaderItem item)_ to write static resources or free-form text into the header section of the page. + +Header entries are instances of abstract class _org.apache.wicket.markup.head.HeaderItem_. Wicket provides a set of built-in implementations of this class suited for the most common types of resources. With the exception of _PriorityHeaderItem_, every implementation of _HeaderItem_ is an abstract factory class: + +* *CssHeaderItem:* represents a CSS resource. Factory methods provided by this class are _forReference_ which takes in input a resource reference, _forUrl_ which creates an CSS item from a given URL and _forCSS_ which takes in input an arbitrary CSS string and an optional id value to identify the resource. +* *JavaScriptHeaderItem:* represents a JavaScript resource. Just like _CssHeaderItem_ it provides factory methods _forReference_ and _forUrl_ along with method _forScript_ which takes in input an arbitrary string representing the script and an optional id value to identify the resource. Method _forReference_ also supports boolean parameter _defer_ which renders the namesake attribute in the script tag (_defer_ attribute indicates that our script must be execute only after the page has loaded). +* *OnDomReadyHeaderItem:* it adds JavaScript code that will be executed after the DOM has been built, but before external files (such as picture, CSS, etc...) have been loaded. The class provides a factory method _forScript_ which takes in input an arbitrary string representing the script to execute. +* *OnEventHeaderItem:* the JavaScript code added with this class is executed when a specific JavaScript event is triggered on a given DOM element. The factory method is _forScript(String target, String event, CharSequence javaScript)_, where target is the id of a DOM element (or the element itself), event is the event that must trigger our code and javaScript is the code to execute. +* *OnLoadHeaderItem:* the JavaScript code added with this class is executed after the whole page is loaded, external files included. The factory method is _forScript(CharSequence javaScript)_. +* *PriorityHeaderItem:* it wraps another header item and ensures that it will have the priority over the other items during rendering phase. +* *StringHeaderItem:* with this class we can add an arbitrary text to the header section. Factory method is _forString(CharSequence string)_. +* *MetaDataHeaderItem:* starting from version 6.17.0, Wicket provides this class to handle meta informations such as <meta> tags or http://en.wikipedia.org/wiki/Canonical_link_element[canonical link element] +* *HtmlImportHeaderItem:* introduced in Wicket 6.19.0, provides a HTML5 functionality to include other wicket pages (other html files) into the current generated. Factory methods provided by this class are _forImportLinkTag_ which takes the page class or the url of the page / html to be included. + + +In the following example our custom component loads a CSS file as a package resource (placed in the same package) and it adds it to header section. + +[source,java] +---- +public class MyComponent extends Component{ + + @Override + public void renderHead(IHeaderResponse response) { + PackageResourceReference cssFile = + new PackageResourceReference(this.getClass(), "style.css"); + CssHeaderItem cssItem = CssHeaderItem.forReference(cssFile); + + response.render(cssItem); + } +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc new file mode 100644 index 0000000..6abf760 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_5.adoc @@ -0,0 +1,44 @@ + +In web applications, it's quite common to have one or more root context folders containing css/js files. These resources are normally referenced with an absolute path inside link/script tags: + +[source,html] +---- +<script src="/misc/js/jscript.js"></script> +<link type="text/css" rel="stylesheet" href="/misc/css/themes/style.css" /> +---- + +To handle this kind of resources from code we can use resource reference class _org.apache.wicket.request.resource.ContextRelativeResourceReference_. To build a new instance of this class we must specify the root context path of the resource we want to use: + +[source,java] +---- +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js"); +---- + +By default when our application runs in DEPLOYMENT mode _ContextRelativeResourceReference_ will automatically load the minified version of the specified resource using 'min' as postfix. In the example above it will load '/misc/js/jscript.min.js'. We can force _ContextRelativeResourceReference_ to always use the not-minified resource passing an additional flag to class constructor: + +[source,java] +---- +//it will always use '/misc/js/jscript.js' +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", false); +---- + +The minified postfix can be customized with an optional string parameter: + +[source,java] +---- +//it will use '/misc/js/jscript.minified.js' in DEPLOYMENT mode +ContextRelativeResourceReference resource = new ContextRelativeResourceReference("/misc/js/jscript.js", "minified"); +---- + +_ContextRelativeResourceReference_ is usually used with the header item classes we have seen before in this chapter to create entries for the page header section. + +=== Picture files + +For picture files Wicket provides a specific component with class _org.apache.wicket.markup.html.image.ContextImage_ which is meant to be used with tag <img> + +[source,java] +---- +//build the component specifying its id and picture's context path +ContextImage image = new ContextImage("myPicture", "/misc/imgs/mypic.png"); +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc new file mode 100644 index 0000000..b40d8b4 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_6.adoc @@ -0,0 +1,30 @@ + + + +Class _ResourceReference_ allows to specify the resources it depends on overriding method _getDependencies()_. The method returns a list of _HeaderItem_s that must be rendered before the resource referenced by _ResourceReference_ can be used. This can be really helpful when our resources are JavaScript or CSS libraries that in turn depend on other libraries. + +For example we can use this method to ensure that a custom reference to JQueryUI library will find JQuery already loaded in the page: + +[source,java] +---- +Url jqueyuiUrl = Url.parse("https://ajax.googleapis.com/ajax/libs/jqueryui/"; + + "1.10.2/jquery-ui.min.js"); + +UrlResourceReference jqueryuiRef = new UrlResourceReference(jqueyuiUrl){ + @Override + public List<HeaderItem> getDependencies() { + Application application = Application.get(); + ResourceReference jqueryRef = application.getJavaScriptLibrarySettings(). + getJQueryReference(); + + return Arrays.asList(JavaScriptHeaderItem.forReference(jqueryRef)); + } +}; +---- + +Please note that in the code above we have built a resource reference using a URL to the desired library instead of a package resource holding the physical file. + +NOTE: Wicket already provides base class _org.apache.wicket.resource.JQueryPluginResourceReference_ for those JavaScript resources that depend on JQuery. This class uses the JQuery version bundled with Wicket. + +NOTE: The same method _getDependencies()_ is defined also for class _HeaderItem_. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc new file mode 100644 index 0000000..0c8a330 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_7.adoc @@ -0,0 +1,26 @@ + +One of the best practices to make our web application faster and reduce its latency is to reduce the number of requests to the server to load page resources like JavaScript or CSS files. To achieve this goal some JavaScript-based build tools (like Grunt) allow to merge multiple files used in a page into a single file that can be loaded in a single request. Wicket provides class _org.apache.wicket.ResourceBundles_ to aggregate multiple resource references into a single one. A resource bundle can be declared during application initialization listing all the resources that compose it: + +[source,java] +---- +@Override +public void init() { + super.init(); + + getResourceBundles().addJavaScriptBundle(WicketApplication.class, + "jqueryUiJs", + jqueryJsReference, + jqueryUiJsReference); + + getResourceBundles().addCssBundle(WicketApplication.class, + "jqueryUiCss", + jqueryCssReference, + jqueryUiCssReference); + +} +---- + +To declare a new resource bundle we need to provide a _scope_ class (_WicketApplication.class_ in our example) and an unique name. Now, when one of the resources included in the bundle is requested, the entire bundle is rendered instead. + +NOTE: A specific resource reference can not be shared among different resource bundles (i.e. it can be part of only one bundle). + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc new file mode 100644 index 0000000..cde2c40 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_8.adoc @@ -0,0 +1,110 @@ + +Some web developers prefer to put their <script> tags at the end of page body and not inside the <head> tags: + +[source,html] +---- + +<html> + +<head> +//no <script> tag here... +</head> + +<body> +... +<script> +//one or more <script> tags at the end of the body +</script> +</body> +</html> + +---- + + +In Wicket we can achieve this result providing a custom _IHeaderResponseDecorator_ to a our application and using Wicket tag <wicket:container/> to indicate where we want to render our scripts inside the page. Interface _IHeaderResponseDecorator_ defines method _IHeaderResponse decorate(IHeaderResponse response)_ which allows to decorate or add functionalities to Wicket _IHeaderResponse_. Our custom _IHeaderResponseDecorator_ can be registered in the application with method _setHeaderResponseDecorator_. Anytime Wicket creates an instance of _IHeaderResponse_, it will call the registered _IHeaderResponseDecorator_ to decorate the header response. + +In the example project _ScriptInsideBody_ we can find a custom _IHeaderResponseDecorator_ that renders CSS into the usual <head> tag and put JavaScricpt header items into a specific container (tag <wicket:container/>) +Wicket already comes with class _JavaScriptFilteredIntoFooterHeaderResponse_ which wraps a _IHeaderResponse_ and renders in a given container all the instances of _JavaScriptHeaderItem_. +The following code is taken from the Application class of the project: + +[source,java] +---- + + //... + @Override + public void init() + { + setHeaderResponseDecorator(new JavaScriptToBucketResponseDecorator("footer-container")); + } + + /** + * Decorates an original IHeaderResponse and renders all javascript items + * (JavaScriptHeaderItem), to a specific container in the page. + */ + static class JavaScriptToBucketResponseDecorator implements IHeaderResponseDecorator + { + + private String bucketName; + + public JavaScriptToBucketResponseDecorator(String bucketName) { + this.bucketName = bucketName; + } + + @Override + public IHeaderResponse decorate(IHeaderResponse response) { + return new JavaScriptFilteredIntoFooterHeaderResponse(response, bucketName); + } + + } +---- + +As you can see in the code above the [bucket] that will contain JavaScript tags is called _ .[footer-container] To make a use of it the developer have to add a special component called _HeaderResponseContainer_ in his page: + +[source,java] +---- +add(new HeaderResponseContainer("someId", "filterName")); +---- + +Please note that _HeaderResponseContainer_'s needs also a name for the corresponding header response's filter. The markup of our page will look like this: + +[source,html] +---- + +<html> + +<header> +//no <script> tag here... +</header> + +<body> +<!-- here we will have our JavaScript tags --> +<wicket:container wicket:id="someId"/> +</body> +</html> + +---- + +The code of the home page is the following: + +[source,java] +---- + public HomePage(final PageParameters parameters) { + super(parameters); + + add(new HeaderResponseContainer("footer-container", "footer-container")); + } + + @Override + public void renderHead(IHeaderResponse response) { + response.render(JavaScriptHeaderItem.forReference(new PackageResourceReference(getClass(), + "javasciptLibrary.js"))); + + response.render(OnEventHeaderItem.forScript("'logo'", "click", "alert('Clicked me!')")); + } +---- + +Looking at the code above you can note that our page adds two script to the header section: the first is an instance of _JavaScriptHeaderItem_ and will be rendered in the _HeaderResponseContainer_ while the second will follow the usual behavior and will be rendered inside <head> tag. + + + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc b/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc new file mode 100644 index 0000000..ce2c65b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/resources/resources_9.adoc @@ -0,0 +1,18 @@ + +Starting from version 6.15.0 we can specify where header contributors must be rendered inside <head> tag using the placeholder tag _<wicket:header-items/>_: + +[source,html] +---- +<head> + <meta charset="UTF-8"/> + <wicket:header-items/> + <script src="my-monkey-patch-of-wicket-ajax.js"></script> +</head> +---- + +With the code above all header contributions done by using IHeaderResponse in your Java code or the special _<wicket:head>_ tag will be put between the <meta> and <script> elements, i.e. in the place of _<wicket:header-items/>_. + +This way you can make sure that some header item is always before or after the header items managed by Wicket. + +_<wicket:header-items/>_ can be used only in the page's <head> element and there could be at most one instance of it. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security.adoc b/wicket-user-guide/src/main/asciidoc/security.adoc new file mode 100644 index 0000000..f499eb1 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security.adoc @@ -0,0 +1,4 @@ + +Security is one of the most important non-functional requirements we must implement in our applications. This is particularly true for enterprise applications as they usually support multiple concurrent users, and therefore they need to have an access control policy. + +In this chapter we will explore the security infrastructure provided by Wicket and we will learn how to use it to implement authentication and authorizations in our web applications. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_1.adoc b/wicket-user-guide/src/main/asciidoc/security/security_1.adoc new file mode 100644 index 0000000..2c288a1 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_1.adoc @@ -0,0 +1,167 @@ + + + +The first step in implementing a security policy is assigning a trusted identity to our users, which means that we must authenticate them. Web applications usually adopt a form-based authentication with a login form that asks user for a unique username and the relative password: + +image::../img/wikipedia-login-form.png[] + +Wicket supports form-based authentication with session class _AuthenticatedWebSession_ and application class _AuthenticatedWebApplication_, both placed inside package _org.apache.wicket.authroles.authentication_. + +=== AuthenticatedWebSession + +Class AuthenticatedWebSession comes with the following set of public methods to manage user authentication: + +* *authenticate(String username, String password)*: this is an abstract method that must be implemented by every subclass of _AuthenticatedWebSession_. It should contain the actual code that checks for user's identity. It returns a boolean value which is true if authentication has succeeded or false otherwise. +* *signIn(String username, String password)*: this method internally calls authenticate and set the flag signedIn to true if authentication succeeds. +* *isSignedIn()*:getter method for flag signedIn. +* *invalidate()*: sets the flag signedIn to false and invalidates session. +* *signOut()*: an alias of *invalidate()*. + +Another abstract method we must implement when we use _AuthenticatedWebSession_ is getRoles which is inherited from parent class _AbstractAuthenticatedWebSession_. This method can be ignored for now as it will be discussed later when we will talk about role-based authorization. + +=== AuthenticatedWebApplication + +Class AuthenticatedWebApplication provides the following methods to support form-based authentication: + +* *getWebSessionClass()*: abstract method that returns the session class to use for this application. The returned class must be a subclass of _AbstractAuthenticatedWebSession_. +* *getSignInPageClass()*: abstract method that returns the page to use as sign in page when a user must be authenticated. +* *restartResponseAtSignInPage()*: forces the current response to restart at the sign in page. After we have used this method to redirect a user, we can make her/him return to the original page calling _Component_'s method _continueToOriginalDestination()_. + +The other methods implemented inside _AuthenticatedWebApplication_ will be introduced when we talk about authorization. + +=== A basic example of authentication + +Project _BasicAuthenticationExample_ is a basic example of form-based authentication implemented with classes _AuthenticatedWebSession_ and _AuthenticatedWebApplication_. + +The homepage of the project contains only a link to page _AuthenticatedPage_ which can be accessed only if user is signed in. The code of _AuthenticatedPage_ is this following: + +[source,java] +---- +public class AuthenticatedPage extends WebPage { + @Override + protected void onConfigure() { + super.onConfigure(); + AuthenticatedWebApplication app = (AuthenticatedWebApplication)Application.get(); + //if user is not signed in, redirect him to sign in page + if(!AuthenticatedWebSession.get().isSignedIn()) + app.restartResponseAtSignInPage(); + } + + @Override + protected void onInitialize() { + super.onInitialize(); + add(new BookmarkablePageLink("goToHomePage", getApplication().getHomePage())); + + add(new Link("logOut") { + + @Override + public void onClick() { + AuthenticatedWebSession.get().invalidate(); + setResponsePage(getApplication().getHomePage()); + } + }); + } +} +---- + +Page _AuthenticatedPage_ checks inside onConfigure if user is signed in and if not, it redirects her/him to the sign in page with method _restartResponseAtSignInPage_. The page contains also a link to the homepage and another link that signs out user. + +The sign in page is implemented in class _SignInPage_ and contains the form used to authenticate users: + +[source,java] +---- +public class SignInPage extends WebPage { + private String username; + private String password; + + @Override + protected void onInitialize() { + super.onInitialize(); + + StatelessForm form = new StatelessForm("form") { + @Override + protected void onSubmit() { + if(Strings.isEmpty(username)) + return; + + boolean authResult = AuthenticatedWebSession.get().signIn(username, password); + //if authentication succeeds redirect user to the requested page + if(authResult) + continueToOriginalDestination(); + } + }; + + form.setModel(new CompoundPropertyModel(this)); + + form.add(new TextField("username")); + form.add(new PasswordTextField("password")); + + add(form); + } +} +---- + +The form is responsible for handling user authentication inside its method _onSubmit()_. The username and password are passed to _AuthenticatedWebSession_'s method _signIn(username, password)_ and if authentication succeeds, the user is redirected to the original page with method _continueToOriginalDestination_. + +The session class and the application class used in the project are reported here: + +*Session class:* + +[source,java] +---- +public class BasicAuthenticationSession extends AuthenticatedWebSession { + + public BasicAuthenticationSession(Request request) { + super(request); + } + + @Override + public boolean authenticate(String username, String password) { + //user is authenticated if both username and password are equal to 'wicketer' + return username.equals(password) && username.equals("wicketer"); + } + + @Override + public Roles getRoles() { + return new Roles(); + } +} +---- + +*Application class:* + +[source,java] +---- +public class WicketApplication extends AuthenticatedWebApplication { + @Override + public Class<HomePage> getHomePage(){ + return HomePage.class; + } + + @Override + protected Class<? extends AbstractAuthenticatedWebSession> getWebSessionClass(){ + return BasicAuthenticationSession.class; + } + + @Override + protected Class<? extends WebPage> getSignInPageClass() { + return SignInPage.class; + } +} +---- + +The authentication logic inside authenticate has been kept quite trivial in order to make the code as clean as possible. Please note also that session class must have a constructor that accepts an instance of class _Request_. + +=== Redirecting user to an intermediate page + +Method _restartResponseAtSignInPage_ is an example of redirecting user to an intermediate page before allowing him to access to the requested page. This method internally throws exception _org.apache.wicket.RestartResponseAtInterceptPageException_ which saves the URL and the parameters of the requested page into session metadata and then redirects user to the page passed as constructor parameter (the sign in page). + +Component's method _redirectToInterceptPage(Page)_ works in much the same way as _restartResponseAtSignInPage_ but it allows us to specify which page to use as intermediate page: + +[source,java] +---- + redirectToInterceptPage(intermediatePage); +---- + +NOTE: Since both _restartResponseAtSignInPage_ and _redirectToInterceptPage_ internally throw an exception, the code placed after them will not be executed. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_2.adoc b/wicket-user-guide/src/main/asciidoc/security/security_2.adoc new file mode 100644 index 0000000..3bc775f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_2.adoc @@ -0,0 +1,288 @@ + + + +The authorization support provided by Wicket is built around the concept of authorization strategy which is represented by interface _IAuthorizationStrategy_ (in package _org.apache.wicket.authorization_): + +[source,java] +---- +public interface IAuthorizationStrategy { + + //interface methods + <T extends IRequestableComponent> boolean isInstantiationAuthorized(Class<T> componentClass); + boolean isActionAuthorized(Component component, Action action); + + //default authorization strategy that allows everything + public static final IAuthorizationStrategy ALLOW_ALL = new IAuthorizationStrategy() + { + @Override + public <T extends IRequestableComponent> boolean isInstantiationAuthorized(final Class<T> c) + { + return true; + } + @Override + public boolean isActionAuthorized(Component c, Action action) + { + return true; + } + }; +} +---- + +This interface defines two methods: + +* _isInstantiationAuthorized()_ checks if user is allowed to instantiate a given component. +* _isActionAuthorized()_ checks if user is authorized to perform a given action on a component's instance. The standard actions checked by this method are defined into class Action and are Action.ENABLE and Action.RENDER. + +Inside _IAuthorizationStrategy_ we can also find a default implementation of the interface (called ALLOW_ALL) that allows everyone to instantiate every component and perform every possible action on it. This is the default strategy adopted by class _Application_. + +To change the authorization strategy in use we must register the desired implementation into security settings (class _SecuritySettings_) during initialization phase with method setAuthorization Strategy: + +[source,java] +---- + //Application class code... + @Override + public void init() + { + super.init(); + getSecuritySettings(). + setAuthorizationStrategy(myAuthorizationStrategy); + } +//... +---- + +If we want to combine the action of two or more authorization strategies we can chain them with strategy _CompoundAuthorizationStrategy_ which implements composite pattern for authorization strategies. + +Most of the times we won't need to implement an _IAuthorizationStrategy_ from scratch as Wicket already comes with a set of built-in strategies. In the next paragraphs we will see some of these strategies that can be used to implement an effective and flexible security policy. + +=== SimplePageAuthorizationStrategy + +Abstract class SimplePageAuthorizationStrategy (in package _org.apache.wicket.authorization.strategies.page_) is a strategy that checks user authorizations calling abstract method _isAuthorized_ only for those pages that are subclasses of a given supertype. If _isAuthorized_ returns false, the user is redirected to the sign in page specified as second constructor parameter: + +[source,java] +---- +SimplePageAuthorizationStrategy authorizationStrategy = new SimplePageAuthorizationStrategy( + PageClassToCheck.class, SignInPage.class) +{ + protected boolean isAuthorized() + { + //Authentication code... + } +}; +---- + +By default _SimplePageAuthorizationStrategy_ checks for permissions only on pages. If we want to change this behavior and check also other kinds of components, we must override method _isActionAuthorized()_ and implement our custom logic inside it. + +=== Role-based strategies + +At the end of <<security.adoc#_authentication,paragraph 22.1>> we have introduced AbstractAuthenticatedWebSession's method getRoles() which is provided to support role-based authorization returning the set of roles granted to the current user. + +In Wicket roles are simple strings like âBASIC_USERâ or âADMINâ (they don't need to be capitalized) and they are handled with class _org.apache.wicket.authroles.authorization.strategies.role.Roles_. This class extends standard HashSet collection adding some functionalities to check whether the set contains one or more roles. Class _Roles_ already defines roles Roles.USER and Roles.ADMIN. + +The session class in the following example returns a custom âSIGNED_INâ role for every authenticated user and it adds an Roles.ADMIN role if username is equal to superuser: + +[source,java] +---- +class BasicAuthenticationRolesSession extends AuthenticatedWebSession { + private String userName; + + public BasicAuthenticationRolesSession(Request request) { + super(request); + } + + @Override + public boolean authenticate(String username, String password) { + boolean authResult= false; + + authResult = //some authentication logic... + + if(authResult) + userName = username; + + return authResult; + } + + @Override + public Roles getRoles() { + Roles resultRoles = new Roles(); + + if(isSignedIn()) + resultRoles.add("SIGNED_IN"); + + if(userName.equals("superuser")) + resultRoles.add(Roles.ADMIN); + + return resultRoles; + } +} +---- + +Roles can be adopted to apply security restrictions on our pages and components. This can be done using one of the two built-in authorization strategies that extend super class _AbstractRoleAuthorizationStrategyWicket_: _MetaDataRoleAuthorizationStrategy_ and _AnnotationsRoleAuthorizationStrategy_ + +The difference between these two strategies is that _MetaDataRoleAuthorizationStrategy_ handles role-based authorizations with Wicket metadata while _AnnotationsRoleAuthorizationStrategy_ uses Java annotations. + +NOTE: Application class _AuthenticatedWebApplication_ already sets _MetaDataRoleAuthorizationStrategy_ and _AnnotationsRoleAuthorizationStrategy_ as its own authorization strategies (it uses a compound strategy as we will see in <<security.adoc#_authorizations,paragraph 22.2>>). + +The code that we will see in the next examples is for illustrative purpose only. If our application class inherits from _AuthenticatedWebApplication_ we won't need to configure anything to use these two strategies. + +==== Using roles with metadata + +Strategy _MetaDataRoleAuthorizationStrategy_ uses application and components metadata to implement role-based authorizations. The class defines a set of static methods authorize that can be used to specify which roles are allowed to instantiate a component and which roles can perform a given action on a component. + +The following code snippet reports both application and session classes from project _MetaDataRolesStrategyExample_ and illustrates how to use _MetaDataRoleAuthorizationStrategy_ to allow access to a given page (AdminOnlyPage) only to ADMIN role: + +*Application class:* + +[source,java] +---- +public class WicketApplication extends AuthenticatedWebApplication { + @Override + public Class<? extends WebPage> getHomePage(){ + return HomePage.class; + } + + @Override + protected Class<? extends AbstractAuthenticatedWebSession> getWebSessionClass() { + return BasicAuthenticationSession.class; + } + + @Override + protected Class<? extends WebPage> getSignInPageClass() { + return SignInPage.class; + } + + @Override + public void init(){ + getSecuritySettings().setAuthorizationStrategy(new MetaDataRoleAuthorizationStrategy(this)); + MetaDataRoleAuthorizationStrategy.authorize(AdminOnlyPage.class, Roles.ADMIN); + } +} +---- + +*Session class:* + +[source,java] +---- +public class BasicAuthenticationSession extends AuthenticatedWebSession { + + private String username; + + public BasicAuthenticationSession(Request request) { + super(request); + } + + @Override + public boolean authenticate(String username, String password) { + //user is authenticated if username and password are equal + boolean authResult = username.equals(password); + + if(authResult) + this.username = username; + + return authResult; + } + + public Roles getRoles() { + Roles resultRoles = new Roles(); + //if user is signed in add the relative role + if(isSignedIn()) + resultRoles.add("SIGNED_IN"); + //if username is equal to 'superuser' add the ADMIN role + if(username!= null && username.equals("superuser")) + resultRoles.add(Roles.ADMIN); + + return resultRoles; + } + + @Override + public void signOut() { + super.signOut(); + username = null; + } +} +---- + +The code that instantiates _MetaDataRoleAuthorizationStrategy_ and set it as application's strategy is inside application class method _init()_. + +Any subclass of _AbstractRoleAuthorizationStrategyWicket_ needs an implementation of interface _IRoleCheckingStrategy_ to be instantiated. For this purpose in the code above we used the application class itself because its base class _AuthenticatedWebApplication_ already implements interface _IRoleCheckingStrategy_. By default _AuthenticatedWebApplication_ checks for authorizations using the roles returned by the current _AbstractAuthenticatedWebSession_. As final step inside init we grant the access to page _AdminOnlyPage_ to ADMIN role calling method authorize. + +The code from session class has three interesting methods. The first is _authenticate()_ which considers as valid credentials every pair of username and password having the same value. The second notable method is _getRoles()_ which returns role SIGNED_IN if user is authenticated and it adds role ADMIN if username is equal to superuser. Finally, we have method _signOut()_ which has been overridden in order to clean the username field used internally to generate roles. + +Now if we run the project and we try to access to _AdminOnlyPage_ from the home page without having the ADMIN role, we will be redirected to the default access-denied page used by Wicket: + +image::../img/authorization-access-denied.png[] + +The access-denied page can be customized using method _setAccessDeniedPage(Class<? extends Page>)_ of setting class _ApplicationSettings_: + +[source,java] +---- + //Application class code... + @Override + public void init(){ + getApplicationSettings().setAccessDeniedPage( + MyCustomAccessDeniedPage.class); + } +---- + +Just like custom âPage expiredâ page (see <<versioningCaching.adoc#_stateful_pages,chapter 8.2.5>>), also custom âAccess deniedâ page must be bookmarkable. + +==== Using roles with annotations + +Strategy _AnnotationsRoleAuthorizationStrategy_ relies on two built-in annotations to handle role-based authorizations. These annotations are _AuthorizeInstantiation_ and _AuthorizeAction_. As their names suggest the first annotation specifies which roles are allowed to instantiate the annotated component while the second must be used to indicate which roles are allowed to perform a specific action on the annotated component. + +In the following example we use annotations to make a page accessible only to signed-in users and to enable it only if user has the ADMIN role: + +[source,java] +---- +@AuthorizeInstantiation("SIGNED_IN") +@AuthorizeAction(action = "ENABLE", roles = {"ADMIN"}) +public class MyPage extends WebPage { + //Page class code... +} +---- + +Remember that when a component is not enabled, user can render it but he can neither click on its links nor interact with its forms. + +Example project _AnnotationsRolesStrategyExample_ is a revisited version of _MetaDataRolesStrategyExample_ where we use _AnnotationsRoleAuthorizationStrategy_ as authorization strategy. To ensure that page _AdminOnlyPage_ is accessible only to ADMIN role we have used the following annotation: + +[source,java] +---- +@AuthorizeInstantiation("ADMIN") +public class AdminOnlyPage extends WebPage { + //Page class code... +} +---- + +=== Catching an unauthorized component instantiation + +Interface _IUnauthorizedComponentInstantiationListener_ (in package _org.apache.wicket.authorization_) is provided to give the chance to handle the case in which a user tries to instantiate a component without having the permissions to do it. The method defined inside this interface is _onUnauthorizedInstantiation(Component)_ and it is executed whenever a user attempts to execute an unauthorized instantiation. + +This listener must be registered into application's security settings with method _setUnauthorizedComponentInstantiationListener_ defined by setting class _SecuritySettings_. In the following code snippet we register a listener that redirect user to a warning page if he tries to do a not-allowed instantiation: + +[source,java] +---- +public class WicketApplication extends AuthenticatedWebApplication{ + //Application code... + @Override + public void init(){ + getSecuritySettings().setUnauthorizedComponentInstantiationListener( + new IUnauthorizedComponentInstantiationListener() { + + @Override + public void onUnauthorizedInstantiation(Component component) { + component.setResponsePage(AuthWarningPage.class); + } + }); + } +} +---- + +In addition to interface _IRoleCheckingStrategy_, class _AuthenticatedWebApplication_ implements also _IUnauthorizedComponentInstantiationListener_ and registers itself as listener for unauthorized instantiations. + +By default _AuthenticatedWebApplication_ redirects users to sign-in page if they are not signed-in and they try to instantiate a restricted component. Otherwise, if users are already signed in but they are not allowed to instantiate a given component, an _UnauthorizedInstantiationException_ will be thrown. + +=== Strategy RoleAuthorizationStrategy + +Class _RoleAuthorizationStrategy_ is a compound strategy that combines both _MetaDataRoleAuthorizationStrategy_ and _AnnotationsRoleAuthorizationStrategy_. + +This is the strategy used internally by _AuthenticatedWebApplication_. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_3.adoc b/wicket-user-guide/src/main/asciidoc/security/security_3.adoc new file mode 100644 index 0000000..32ea089 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_3.adoc @@ -0,0 +1,61 @@ + + + +HTTPS is the standard technology adopted on Internet to create a secure communication channel between web applications and their users. + +In Wicket we can easily protect our pages with HTTPS mounting a special request mapper called _HttpsMapper_ and using annotation _RequireHttps_ with those pages we want to serve over this protocol. Both these two entities are in package _org.apache.wicket.protocol.https_. + +_HttpsMapper_ wraps an existing mapper and redirects incoming requests to HTTPS if the related response must render a page annotated with _RequireHttps_. Most of the times the wrapped mapper will be the root one, just like we saw before for _CryptoMapper_ in <<urls.adoc#_generating_structured_and_clear_urls,paragraph 10.6>>. + +Another parameter needed to build a _HttpsMapper_ is an instance of class _HttpsConfig_. This class allows us to specify which ports must be used for HTTPS and HTTP. By default the port numbers used by these two protocols are respectively 443 and 80. + +The following code is taken from project _HttpsProtocolExample_ and illustrates how to enable HTTPS in our applications: + +[source,java] +---- +//Application class code... +@Override +public void init(){ + setRootRequestMapper(new HttpsMapper(getRootRequestMapper(), + new HttpsConfig(8080, 8443))); +} +---- + +Now we can use annotation _RequireHttps_ to specify which pages must be served using HTTPS: + +[source,java] +---- +@RequireHttps +public class HomePage extends WebPage { + public HomePage(final PageParameters parameters) { + super(parameters); + } +} +---- + +If we want to protect many pages with HTTPS without adding annotation _RequireHttps_ to each of them, we can annotate a marker interface or a base page class and implement/extend it in any page we want to make secure: + +[source,java] +---- +// Marker interface: +@RequireHttps +public interface IMarker { +} + +// Base class: +@RequireHttps +public class BaseClass extends WebPage { +//Page code... +} + +// Secure page inheriting from BaseClass: +public class HttpsPage extends BaseClass { +//Page code... +} + +// Secure page implementing IMarker: +public class HttpsPage implements IMarker { +//Page code... +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_4.adoc b/wicket-user-guide/src/main/asciidoc/security/security_4.adoc new file mode 100644 index 0000000..64a7f56 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_4.adoc @@ -0,0 +1,43 @@ + +In chapter <<urls.adoc#_generating_structured_and_clear_urls,10.6>> we have seen how to encrypt URLs using _CryptoMapper_ request mapper. To encrypt/decrypt page URLs _CryptoMapper_ uses an instance of _org.apache.wicket.util.crypt.ICrypt_ interface: + +[source,java] +---- +public interface ICrypt +{ + String encryptUrlSafe(final String plainText); + + String decryptUrlSafe(final String encryptedText); + + ... +} +---- + +The default implementation for this interface is class _org.apache.wicket.util.crypt.SunJceCrypt_. It provides password-based cryptography using _PBEWithMD5AndDES_ algorithm coming with the standard security providers in the Java Runtime Environment. + +NOTE: For better security it is recommended to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html[Policy Files] + +By using _CryptoMapper(IRequestMapper wrappedMapper, Application application)_ constructor the mapper will use the configured _org.apache.wicket.util.crypt.ICryptFactory_ from _org.apache.wicket.settings.SecuritySettings1.getCryptFactory()_. To use a stronger cryptography mechanism there are the following options: + +* The first option is to use constructor _CryptoMapper(IRequestMapper wrappedMapper, Supplier<ICrypt> cryptProvider)_ and give it an implementation of _java.util.function.Supplier_ that returns a custom _org.apache.wicket.util.crypt.ICrypt_. + +* The second option is to register a cipher factory at application level with method _setCryptFactory(ICryptFactory cryptFactory)_ of class _SecuritySettings_: + +[source,java] +---- +@Override +public void init() { + super.init(); + getSecuritySettings().setCryptFactory(new SomeCryptFactory()); + setRootRequestMapper(new CryptoMapper(getRootRequestMapper(), this)); +} +---- + + +Since version 6.19.0 Wicket uses _org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory_ as a default factory for _ICrypt_ objects. This factory generates a unique key for each user that is stored in her HTTP +session. This way it helps to protect the application against https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)[CSRF] +for each user of the application. The url itself serves as https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_Prevention_Cheat_Sheet#Encrypted_Token_Pattern[encrypted token] + +WARNING: _org.apache.wicket.core.util.crypt.KeyInSessionSunJceCryptFactory_ binds the http session if it is not already bound! If the application needs to run in stateless mode then the application will have to provide a custom +implementation of _ICryptFactory_ that stores the user specific keys by other means. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc b/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc new file mode 100644 index 0000000..ce801ba --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_4_1.adoc @@ -0,0 +1,21 @@ + + +_CryptoMapper_ helps preventing CSRF attacks by making the urls impossible to be guessed by an attacker but still there is some theoretical chance this to happen. + +To further help against this kind of vulnerability Wicket provides _CsrfPreventionRequestCycleListener_ - a _IRequestCycleListener_ that forbids requests made from a different origin. By default only actions are forbidden, i.e. a request coming from different origin cannot execute _Link1.onClick()_ or submit forms (_Form1.onSubmit()_). Any request to render pages are still allowed so Wicket pages could be easily embedded in other applications. + +MyApplication.java +[source,java] +---- + @Override + protected void init() { + super.init(); + getRequestCycleListeners().add(new CsrfPreventionRequestCycleListener()); + // ... + } +---- + +_CsrfPreventionRequestCycleListener_ is highly configurable. It allows to define a whitelist of allowed origins via _addAcceptedOrigin(String acceptedOrigin)_, to enable/disable it dynamically by overriding _isEnabled()_, to define different kind of actions when a request is rejected or allowed, to set custom error message and code for the rejected requests. + +_CsrfPreventionRequestCycleListener_ is not an alternative to _CryptoMapper_! Both of them could be used separately or in tandem to prevent CSRF attacks depending on the application requirements. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_5.adoc b/wicket-user-guide/src/main/asciidoc/security/security_5.adoc new file mode 100644 index 0000000..ed02541 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_5.adoc @@ -0,0 +1,44 @@ + + + +Wicket internally uses an entity called package resource guard to protect package resources from external access. This entity is an implementation of interface _org.apache.wicket.markup.html.IPackageResourceGuard_. + +By default Wicket applications use as package resource guard class _SecurePackageResourceGuard_, which allows to access only to the following file extensions (grouped by type): + +|=== +|File | Extensions +|*JavaScript files* |.js +|*CSS files* |.css +|*HTML pages* |.html +|*Textual files* |.txt +|*Flash files* |.swf +|*Picture files* |.png, .jpg, .jpeg, .gif, .ico, .cur, .bmp, .svg +|*Web font files* |.eot, .ttf, .woff +|=== + +To modify the set of allowed files formats we can add one or more patterns with method _addPattern(String)_. The rules to write a pattern are the following: + +* patterns start with either a [+] or a [-] In the first case the pattern will add one or more file to the set while starting a pattern with a â-â we exclude all the files matching the given pattern. For example pattern â-web.xmlâ excludes all web.xml files in all directories. +* wildcard character â\*â is supported as placeholder for zero or more characters. For example pattern â+\*.mp4â adds all the mp4 files inside all directories. +* subdirectories are supported as well. For example pattern â+documents/\*.pdfâ adds all pdf files under âdocumentsâ directory. Character â\*â can be used with directories to specify a nesting level. For example â+documents/\*/\*.pdfâ adds all pdf files placed one level below âdocumentsâ directory. +* a double wildcard character â\*\*â indicates zero or more subdirectories. For example pattern â+documents/\*\*/\*.pdfâ adds all pdf files placed inside âdocumentsâ directory or inside any of its subdirectories. + +Patterns that allow to access to every file with a given extensions (such as â+\*.pdfâ) should be always avoided in favour of more restrictive expressions that contain a directory structure: + +[source,java] +---- +//Application class code... +@Override +public void init() +{ + IPackageResourceGuard packageResourceGuard = application.getResourceSettings() + .getPackageResourceGuard(); + if (packageResourceGuard instanceof SecurePackageResourceGuard) + { + SecurePackageResourceGuard guard = (SecurePackageResourceGuard) packageResourceGuard; + //Allow to access only to pdf files placed in the âpublicâ directory. + guard.addPattern("+public/*.pdf"); + } +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_6.adoc b/wicket-user-guide/src/main/asciidoc/security/security_6.adoc new file mode 100644 index 0000000..f6db43f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_6.adoc @@ -0,0 +1,45 @@ + +Since Mozilla released their site to check if web pages have security issues named https://observatory.mozilla.org[Mozilla Observatory] +a few things which can be done to get a high grade within this ranking without using further frameworks. + +Add a request cycle listener to your web application and adjust the headers to fit your requirements: +[source,java] +---- +@Override +protected void init() +{ + super.init(); + + getRequestCycleListeners().add(new AbstractRequestCycleListener(){ + + @Override + public void onEndRequest(RequestCycle cycle) + { + WebResponse response = (WebResponse) cycle.getResponse(); + response.setHeader("X-XSS-Protection", "1; mode=block"); + response.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains; preload"); + response.setHeader("X-Content-Type-Options", "nosniff"); + response.setHeader("X-Frame-Options", "sameorigin"); + response.setHeader("Content-Security-Policy", "default-src https:"); + } + }); +} +---- + +Add this configuration to your web.xml (or let your server redirect to https): +[source,xml] +---- +<?xml version="1.0" encoding="UTF-8"?> +<security-constraint> + <web-resource-collection> + <web-resource-name>Entire Application</web-resource-name> + <url-pattern>/*</url-pattern> + </web-resource-collection> + <user-data-constraint> + <transport-guarantee>CONFIDENTIAL</transport-guarantee> + </user-data-constraint> +</security-constraint> +---- + +After this changes you have to check if your web application continues to work because it fits the requirements given with these headers. For example that resources could not be requested from other domains anymore. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/security/security_7.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/security/security_7.adoc b/wicket-user-guide/src/main/asciidoc/security/security_7.adoc new file mode 100644 index 0000000..b36dfd5 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/security/security_7.adoc @@ -0,0 +1,16 @@ + + + + In this chapter we have seen the components and the mechanisms that allow us to implement security policies in our Wicket-based applications. Wicket comes with an out of the box support for both authorization and authentication. + +The central element of authorization mechanism is the interface _IAuthorizationStrategy_ which decouples our components from any detail about security strategy. The implementations of this interface must decide if a user is allowed to instantiate a given page or component and if she/he can perform a given action on it. + +Wicket natively supports role-based authorizations with strategies _MetaDataRoleAuthorizationStrategy_ and _AnnotationsRoleAuthorizationStrategy_. The difference between these two strategies is that the first offers a programmatic approach for role handling while the second promotes a declarative approach using built-in annotations. + +After having explored how Wicket internally implements authentication and authorization, in the last part of the chapter we have learnt how to configure our applications to support HTTPS and how to specify which pages must be served over this protocol. + +In the last paragraph we have seen how Wicket protects package resources with a guard entity that allows us to decide which package resources can be accessed from users. + + + +
![http://www.google.de/test.jpg"](https://www.google.de/test.jpg"){kind=link}