DelegateTo.java

/*******************************************************************************
 * Copyright (c) 2012-2015 Codenvy, S.A.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *   Codenvy, S.A. - initial API and implementation
 *******************************************************************************/
package org.eclipse.che.dto.shared;

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

/**
 * Annotation that contains "rules" for delegation invocation of DTO method to some third party classes. In some case we may need more then
 * just getters and setters in DTO, but there is no common mechanism to generate such implementation for DTO interface. In this case this
 * annotation may help. Here is example of usage:
 * <p/>
 * <ol>
 * <li>
 * DTO interface. It contains getters, setters and with methods and we do nothing special for them. Implementation generated automatically
 * as well for client and server side. But if we want to have more complex method generator doesn't help, for example add some method for
 * getting full name of user.
 * <pre>
 * @DTO
 * public interface User {
 *     String getFirstName();
 *
 *     void setFirstName(String firstName);
 *
 *     User withFirstName(String firstName);
 *
 *     String getLastName();
 *
 *     void setLastName(String lastName);
 *
 *     User withLastName(String lastName);
 *
 *     @DelegateTo(client = @DelegateRule(type = Util.class, method = "fullName"),
 *                 server = @DelegateRule(type = Util.class, method = "fullName"))
 *     String getFullName();
 * }
 * </pre>
 * For method {@code getFullName} add annotation {@code @DelegateTo}. Annotations may contains different delegate rules for client and
 * server side.
 * <p/>
 * <div>DelegateTo</div>
 * <table border="0" cellpadding="1" cellspacing="0">
 * <tr align="left">
 * <th align="left">Parameter</th>
 * <th align="left">Description</th>
 * </tr>
 * <tr><td>client</td><td>Rules for client</td></tr>
 * <tr><td>server</td><td>Rules for server</td></tr>
 * </table>
 * <div>DelegateRule</div>
 * <table border="0" cellpadding="1" cellspacing="0">
 * <tr align="left">
 * <th align="left">Parameter</th>
 * <th align="left">Description</th>
 * </tr>
 * <tr><td>type</td><td>Class that contains method to delegate method call</td></tr>
 * <tr><td>method</td><td>Name of method</td></tr>
 * </table>
 * </li>
 * <li>
 * Util class
 * <pre>
 * public class Util {
 *     public static String fullName(User user) {
 *         return user.getFirstName() + " " + user.getLastName();
 *     }
 * }
 * </pre>
 * </li>
 * <li>
 * Requirements for methods to delegate DTO methods calls: Method must be public and static. Method must accept DTO interface as first
 * parameter, if DTO method contains other parameters then the delegate method must accept the whole set of DTO method parameters starting
 * from the second position. For example:
 * <p/>
 * DTO method:
 * <pre>
 * @DelegateTo(client = @DelegateRule(type = Util.class, method = "fullName"),
 *             server = @DelegateRule(type = Util.class, method = "fullName"))
 * String getFullNameWithPrefix(String prefix);
 * </pre>
 * <p/>
 * Delegate method:
 * <pre>
 * public static String fullName(User user, String prefix) {
 *         return prefix + " " + user.getFirstName() + " " + user.getLastName();
 * }
 * </pre>
 * </ul>
 * </li>
 * </ol>
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface DelegateTo {
    DelegateRule client();

    DelegateRule server();
}