net.contextfw.web.application.remote.PathParam Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of web-application Show documentation
Context Web Application Framework
The newest version!
/**
 * Copyright 2010 Marko Lavikainen
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package net.contextfw.web.application.remote;

import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;


/**
 * 
 *  Defines that the field or method contains encoded value from URL-path
 * 
 * 
 * 
 *  Path parameter are encoded to URL-definitions with special syntax and it
 *  works on both path-based and regex-based syntaxes. Path parameters are encoded as
 *  <paramName>.
 * 
 * 
 * General usage
 * 
 * 
 *  This annotation can be applied to view component class properties or methods that take the expected
 *  type as singular parameter. When view components are initialized such methods and parameters
 *  are scanned and values are inserted. By default the class property name or method name is used
 *  to resolve parameter name. This can be overridden by using name.
 * 
 * 
 * 
 *  At this points primitives and their wrappers are supported. Also any class having a 
 *  String-parametrized contructor is supported.
 * 
 * 
 * Mapping in path-style URLs
 * 
 * 
 *  In path-style URLs path parameter is replaced with * and does not match 
 *  with character /. 
 *  For example, following definition:
 * 
 * 
 *  /customers/<id>
 * 
 * 
 *  is translated into following path
 * 
 * 
 *  /customers/*
 * 
 * 
 * Mapping in regex-style URLs
 * 
 * 
 *  In regex-style URLs path parameter is replaced as default with ([^/]+), so it basically
 *  works the same way as path-based variant. With regex-based path it is also possible to 
 *  create different replacement for path-variable, which happens as 
 *  <paramName:regex>.  For example following definition:
 * 
 * 
 *  reges:/engine/<id>/mode/<mode:started|stopped>
 * 
 * 
 *  is translated into following path
 * 
 * 
 *  regex:/engine/([^/]+)/mode/(started|stopped)
 * 
 * 
 * Important caveat on initialization
 * 
 * 
 *  It is important to notice that parameters are not initialized during injection. That is 
 *  parameters are not initialized at @PostConstruct-time. To access them, view component
 *  needs to implement ViewComponent-interface thus initialization is ready when method
 *  initialize() is called. 
 * 
 * 
 * Exceptional handling
 * 
 * 
 *  Because path parameters are about URLs it is very likely that there will be malformed URLs
 *  and those cases must be handled somehow. To tackle those cases there are two handler
 *  onError and onNull.
 * 
 * @see ErrorResolution
 * 
 */
@Target({FIELD, METHOD})
@Retention(RUNTIME)
public @interface PathParam {
    /**
     * The name of the path parameter
     */
    String name() default "";
    /**
     * The resolution when mapping parameter to required type fails. 
     */
    ErrorResolution onError() default ErrorResolution.SEND_NOT_FOUND_ERROR;
    /**
     * The resolution when parameter is null
     */
    ErrorResolution onNull() default ErrorResolution.SET_TO_NULL;
}