/*
 * Copyright 2009 Google Inc.
 *
 * 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 com.google.gwt.uibinder.rebind;

import com.google.gwt.core.ext.UnableToCompleteException;
import com.google.gwt.core.ext.typeinfo.JClassType;
import com.google.gwt.core.ext.typeinfo.JType;
import com.google.gwt.core.ext.typeinfo.TypeOracle;
import com.google.gwt.uibinder.rebind.model.OwnerField;

/**
 * Models a field to be written in the generated binder code. Note that this is
 * not necessarily a field that the user has declared. It's basically any
 * variable the generated UiBinder#createAndBindUi implementation will need.
 * <p>
 * A field can have a custom initialization statement, set via
 * {@link #setInitializer}. Without one it will be initialized via a
 * {@link com.google.gwt.core.client.GWT#create} call. (In the rare case that
 * you need a field not to be initialized, initialize it to "null".)
 * <p>
 * Dependencies can be declared between fields via {@link #needs}, to ensure
 * that one can be initialized via reference to another. Circular references are
 * not supported, nor detected.
 */
public interface FieldWriter {

  /**
   * Add a statement to be executed right after the current field is attached.
   *
   * <pre>
   *   HTMLPanel panel = new HTMLPanel(
   *      "<span id='someId' class='someclass'></span>...");
   *
   *   // statement section.
   *   widgetX.setStyleName("someCss");
   *   widgetX.setVisible(true);
   *
   *   // attach section.
   *   UiBinderUtil.TempAttachment attachRecord =
   *      UiBinderUtil.attachToDom(panel.getElement());
   *   get_domId0Element().get();
   *   get_domId1Element().get();
   *
   *   // detach section.
   *   attachRecord.detach();
   *   panel.addAndReplaceElement(get_someWidget(), get_domId0Element().get());
   *   panel.addAndReplaceElement(get_otherWidget(), get_domId1Element().get());
   * </pre>
   */
  void addAttachStatement(String format, Object... args);

  /**
   * Add a statement to be executed right after the current field is detached.
   * {@see #addAttachStatement}.
   */
  void addDetachStatement(String format, Object... args);

  /**
   * Add a statement for the given field, executed right after its creation. Example:
   *
   * <pre>
   *   WidgetX widgetX = GWT.create(WidgetX.class);
   *
   *   // statement section.
   *   widgetX.setStyleName("someCss");
   *   widgetX.setVisible(true);
   * </pre>
   */
  void addStatement(String format, Object... args);

  /**
   * Returns the type of this field, or for generated types the type it extends.
   */
  // TODO(rjrjr) When ui:style is able to implement multiple interfaces,
  // this will need to become a set
  JClassType getAssignableType();

  /**
   * Gets this field builder precedence.
   */
  int getBuildPrecedence();

  /**
   * Gets the type of this field.
   */
  FieldWriterType getFieldType();

  /**
   * Returns the string html representation of the field.
   */
  String getHtml();

  /**
   * Returns the custom initializer for this field, or null if it is not set.
   */
  String getInitializer();

  /**
   * Returns the type of this field, or null if this field is of a type that has
   * not yet been generated.
   */
  JClassType getInstantiableType();

  /**
   * Get the name of the field.
   */
  String getName();
  
  /**
   * Returns the expression that to evaluate to get the contents of this field.
   * Keeps a reference count, so if the field is to be used more than once it is
   * important to call this method each time.
   */
  String getNextReference();

  /**
   * Returns the qualified source name of this type.
   */
  String getQualifiedSourceName();

  /**
   * Returns the return type found at the end of the given method call
   * path, which must begin with the receiver's name, or null if the
   * path is invalid.
   */
  JType getReturnType(String[] path, MonitoredLogger logger);

  /**
   * Returns the string SafeHtml representation of the field.
   */
  String getSafeHtml();

  /**
   * Declares that the receiver depends upon the given field.
   */
  void needs(FieldWriter f);

  /**
   * Sets the precedence of this field builder. Field with higher values are
   * written first. This is automatically set by FieldManager when the field is
   * created. You should only change it somewhere else if you <b>really</b> know
   * what you are doing.
   */
  void setBuildPrecedence(int precedence);

  /**
   * Sets the html representation of the field for applicable field types.
   */
  void setHtml(String html);

  /**
   * Used to provide an initializer string to use instead of a
   * {@link com.google.gwt.core.client.GWT#create} call. Note that this is an
   * RHS expression. Don't include the leading '=', and don't end it with ';'.
   *
   * @throws IllegalStateException on second attempt to set the initializer
   */
  void setInitializer(String initializer);

  /**
   * Write the field declaration.
   */
  void write(IndentedWriter w) throws UnableToCompleteException;

  /**
   * Write this field builder in the <b>Widgets</b> inner class. There are 3
   * possible situations:
   *
   * <dl>
   *   <dt>getter never called</dt>
   *     <dd>write builder only if there's a ui:field associated</dd>
   *   <dt>getter called only once</dt>
   *     <dd>don't need to write the builder since the getter fallback to the
   *      builder when called</dd>
   *   <dt>getter called more than once</dt>
   *     <dd>in this case a field class is created, the builder is written
   *      and the getter returns the field class</dd>
   * </dl>
   *
   * {@see com.google.gwt.uibinder.rebind.FieldWriter#writeFieldGetter}.
   */
  void writeFieldBuilder(IndentedWriter w, int getterCount, OwnerField ownerField)
      throws UnableToCompleteException;

  /**
   * Output the getter and builder definitions for the given field.
   *
   *  <p>
   *  <b>Example for widgets called only once:</b>
   *  <pre>
   *  private WidgetX get_widgetX() {
   *    return build_widgetX();
   *  }
   *  private WidgetX build_widgetX() {
   *   widget = GWT.create(WidgetX.class);
   *   widget.setStyleName("css");
   *   return widgetX;
   *  }
   *  </pre>
   *  Notice that there's no field and the getter just fallback to the builder.
   *  </p>
   *
   *  <p><b>Example for widgets called more than once:</b>
   *  <pre>
   *  private WidgetX widgetX;
   *  private WidgetX get_widgetX() {
   *    return widgetX;
   *  }
   *  private WidgetX build_widgetX() {
   *   widget = GWT.create(WidgetX.class);
   *   widget.setStyleName("css");
   *   return widgetX;
   *  }
   * </pre>
   * Notice that the getter just returns the field. The builder is called in
   * the Widgets ctor.
   * </p>
   */
  void writeFieldDefinition(IndentedWriter w, TypeOracle typeOracle,
      OwnerField ownerField, DesignTimeUtils designTime, int getterCount,
      boolean useLazyWidgetBuilders)
      throws UnableToCompleteException;
}