1.1 --- a/json/src/main/java/org/apidesign/html/json/spi/Proto.java	Sun Jan 05 08:51:20 2014 +0100
     1.2 +++ b/json/src/main/java/org/apidesign/html/json/spi/Proto.java	Sun Jan 05 21:36:33 2014 +0100
     1.3 @@ -45,13 +45,20 @@
     1.4  import java.util.Collection;
     1.5  import java.util.List;
     1.6  import net.java.html.BrwsrCtx;
     1.7 +import net.java.html.json.Model;
     1.8  import org.netbeans.html.json.impl.Bindings;
     1.9  import org.netbeans.html.json.impl.JSON;
    1.10  import org.netbeans.html.json.impl.JSONList;
    1.11  import org.netbeans.html.json.impl.RcvrJSON;
    1.12  import org.netbeans.html.json.impl.RcvrJSON.MsgEvnt;
    1.13  
    1.14 -/**
    1.15 +/** Object associated with one instance of a model generated by the
    1.16 + * {@link Model} annotation. Contains methods the generated class can
    1.17 + * use to communicate with behind the scene associated {@link Technology}.
    1.18 + * Each {@link Proto} object is associated with <a href="http://wiki.apidesign.org/wiki/Singletonizer">
    1.19 + * singletonizer</a>-like interface {@link Type} which provides the 
    1.20 + * associated {@link Technology} the necessary information about the 
    1.21 + * generated {@link Model} class.
    1.22   *
    1.23   * @author Jaroslav Tulach <jtulach@netbeans.org>
    1.24   * @since 0.7
    1.25 @@ -69,19 +76,34 @@
    1.26          this.context = context;
    1.27      }
    1.28  
    1.29 +    /** Browser context this proto object and its associated model
    1.30 +     * are operating-in.
    1.31 +     * 
    1.32 +     * @return the associated context 
    1.33 +     */
    1.34      public BrwsrCtx getContext() {
    1.35          return context;
    1.36      }
    1.37 -    
    1.38 +
    1.39 +    /** Before doing modification of the model properties, the
    1.40 +     * generated code enters write lock by calling this method.
    1.41 +     * @throws IllegalStateException if already locked
    1.42 +     */
    1.43      public void acquireLock() throws IllegalStateException {
    1.44          if (locked) throw new IllegalStateException();
    1.45          locked = true;
    1.46      }
    1.47      
    1.48 -    public void checkLock() throws IllegalStateException {
    1.49 +    /** Verifies the model is not locked otherwise throws an exception.
    1.50 +     * @throws IllegalStateException if the model is locked
    1.51 +     */
    1.52 +    public void verifyUnlocked() throws IllegalStateException {
    1.53          if (locked) throw new IllegalStateException();
    1.54      }
    1.55      
    1.56 +    /** When modifications are over, the model is switched into 
    1.57 +     * unlocked state by calling this method.
    1.58 +     */
    1.59      public void releaseLock() {
    1.60          locked = false;
    1.61      }

     2.1 --- a/json/src/main/java/org/netbeans/html/json/impl/ModelProcessor.java	Sun Jan 05 08:51:20 2014 +0100
     2.2 +++ b/json/src/main/java/org/netbeans/html/json/impl/ModelProcessor.java	Sun Jan 05 21:36:33 2014 +0100
     2.3 @@ -521,18 +521,18 @@
     2.4              
     2.5                  castTo = "java.util.List";
     2.6                  w.write("  public java.util.List<" + tn + "> " + gs[0] + "() {\n");
     2.7 -                w.write("    proto.checkLock();\n");
     2.8 +                w.write("    proto.verifyUnlocked();\n");
     2.9                  w.write("    return prop_" + p.name() + ";\n");
    2.10                  w.write("  }\n");
    2.11              } else {
    2.12                  castTo = tn;
    2.13                  w.write("  private " + tn + " prop_" + p.name() + ";\n");
    2.14                  w.write("  public " + tn + " " + gs[0] + "() {\n");
    2.15 -                w.write("    proto.checkLock();\n");
    2.16 +                w.write("    proto.verifyUnlocked();\n");
    2.17                  w.write("    return prop_" + p.name() + ";\n");
    2.18                  w.write("  }\n");
    2.19                  w.write("  public void " + gs[1] + "(" + tn + " v) {\n");
    2.20 -                w.write("    proto.checkLock();\n");
    2.21 +                w.write("    proto.verifyUnlocked();\n");
    2.22                  w.write("    if (TYPE.isSame(prop_" + p.name() + ", v)) return;\n");
    2.23                  w.write("    prop_" + p.name() + " = v;\n");
    2.24                  w.write("    proto.valueHasMutated(\"" + p.name() + "\");\n");