net.java.html.json.OnPropertyChange Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of net.java.html.json Show documentation

API for smooth representation of JSON objects in Java. Write your application in Java and present it using modern HTML rendering technologies like Knockout.

The newest version!

/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.java.html.json;

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

/** Marks a method that is going to be notified when a 
 * property defined by {@link Model} has been changed. This is
 * especially useful when one wants to react to changes in the 
 * model caused by the rendered view. In case of 
 * knockout.js technology
 * one could for example react to selection of a name from a combo
 * box:
 *  * 
 * <!-- associates the selected value with property name -->
 * 
 * <select data-bind="value: name">
 *   <option>Jiří</option>
 *   <option>Jarda</option>
 *   <option>Petr</option>
 *   <option>Tomáš</option>
 * </select>
 * 
 * // Java code snippet reacting to change of the name property:
 * 
 * {@link OnPropertyChange @OnPropertyChange}("name") 
 * static void propertyChanged(AModel inst, {@link String} propertyName) {
 *   // schedule some operation
 *   // on the model
 * }
 * 
 * The method's first argument should be the instance of the 
 * associated {@link Model model class}. The method shall be non-private
 * and unless {@link Model#instance() instance mode} is on also static.
 * There can be an optional second {@link String} argument which will be set
 * to the name of the changed property. The second argument is only useful when
 * a single method reacts to changes in multiple properties.
 * 
 * An online example using this technique is 
 * available here -
 * it observes selection in a combo box and in case it changes 
 * the example sends a network
 * request and {@link net.java.html.json.OnReceive asynchronously updates}
 * list of code snippets.
 *
 * @author Jaroslav Tulach
 */
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.METHOD)
public @interface OnPropertyChange {
    /** Name(s) of the properties. One wishes to observe.
     * 
     * @return valid java identifier
     */
    String[] value();
}