Subversion Repositories Code-Repo

// Protocol Buffers - Google's data interchange format

// Copyright 2008 Google Inc.  All rights reserved.

// http://code.google.com/p/protobuf/

//

// Redistribution and use in source and binary forms, with or without

// modification, are permitted provided that the following conditions are

// met:

//

//     * Redistributions of source code must retain the above copyright

// notice, this list of conditions and the following disclaimer.

//     * Redistributions in binary form must reproduce the above

// copyright notice, this list of conditions and the following disclaimer

// in the documentation and/or other materials provided with the

// distribution.

//     * Neither the name of Google Inc. nor the names of its

// contributors may be used to endorse or promote products derived from

// this software without specific prior written permission.

//

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package com.google.protobuf;

/**

 * <code>SingleFieldBuilder</code> implements a structure that a protocol

 * message uses to hold a single field of another protocol message. It supports

 * the classical use case of setting an immutable {@link Message} as the value

 * of the field and is highly optimized around this.

 * <br>

 * It also supports the additional use case of setting a {@link Message.Builder}

 * as the field and deferring conversion of that <code>Builder</code>

 * to an immutable <code>Message</code>. In this way, it's possible to maintain

 * a tree of <code>Builder</code>'s that acts as a fully read/write data

 * structure.

 * <br>

 * Logically, one can think of a tree of builders as converting the entire tree

 * to messages when build is called on the root or when any method is called

 * that desires a Message instead of a Builder. In terms of the implementation,

 * the <code>SingleFieldBuilder</code> and <code>RepeatedFieldBuilder</code>

 * classes cache messages that were created so that messages only need to be

 * created when some change occured in its builder or a builder for one of its

 * descendants.

 *

 * @param <MType> the type of message for the field

 * @param <BType> the type of builder for the field

 * @param <IType> the common interface for the message and the builder

 *

 * @author jonp@google.com (Jon Perlow)

 */

public class SingleFieldBuilder

    <MType extends GeneratedMessage,

     BType extends GeneratedMessage.Builder,

     IType extends MessageOrBuilder>

    implements GeneratedMessage.BuilderParent {

  // Parent to send changes to.

  private GeneratedMessage.BuilderParent parent;

  // Invariant: one of builder or message fields must be non-null.

  // If set, this is the case where we are backed by a builder. In this case,

  // message field represents a cached message for the builder (or null if

  // there is no cached message).

  private BType builder;

  // If builder is non-null, this represents a cached message from the builder.

  // If builder is null, this is the authoritative message for the field.

  private MType message;

  // Indicates that we've built a message and so we are now obligated

  // to dispatch dirty invalidations. See GeneratedMessage.BuilderListener.

  private boolean isClean;

  public SingleFieldBuilder(

      MType message,

      GeneratedMessage.BuilderParent parent,

      boolean isClean) {

    if (message == null) {

      throw new NullPointerException();

    }

    this.message = message;

    this.parent = parent;

    this.isClean = isClean;

  }

  public void dispose() {

    // Null out parent so we stop sending it invalidations.

    parent = null;

  }

  /**

   * Get the message for the field. If the message is currently stored

   * as a <code>Builder</code>, it is converted to a <code>Message</code> by

   * calling {@link Message.Builder#buildPartial} on it. If no message has

   * been set, returns the default instance of the message.

   *

   * @return the message for the field

   */

  @SuppressWarnings("unchecked")

  public MType getMessage() {

    if (message == null) {

      // If message is null, the invariant is that we must be have a builder.

      message = (MType) builder.buildPartial();

    }

    return message;

  }

  /**

   * Builds the message and returns it.

   *

   * @return the message

   */

  public MType build() {

    // Now that build has been called, we are required to dispatch

    // invalidations.

    isClean = true;

    return getMessage();

  }

  /**

   * Gets a builder for the field. If no builder has been created yet, a

   * builder is created on demand by calling {@link Message#toBuilder}.

   *

   * @return The builder for the field

   */

  @SuppressWarnings("unchecked")

  public BType getBuilder() {

    if (builder == null) {

      // builder.mergeFrom() on a fresh builder

      // does not create any sub-objects with independent clean/dirty states,

      // therefore setting the builder itself to clean without actually calling

      // build() cannot break any invariants.

      builder = (BType) message.newBuilderForType(this);

      builder.mergeFrom(message); // no-op if message is the default message

      builder.markClean();

    }

    return builder;

  }

  /**

   * Gets the base class interface for the field. This may either be a builder

   * or a message. It will return whatever is more efficient.

   *

   * @return the message or builder for the field as the base class interface

   */

  @SuppressWarnings("unchecked")

  public IType getMessageOrBuilder() {

    if (builder != null) {

      return  (IType) builder;

    } else {

      return (IType) message;

    }

  }

  /**

   * Sets a  message for the field replacing any existing value.

   *

   * @param message the message to set

   * @return the builder

   */

  public SingleFieldBuilder<MType, BType, IType> setMessage(

      MType message) {

    if (message == null) {

      throw new NullPointerException();

    }

    this.message = message;

    if (builder != null) {

      builder.dispose();

      builder = null;

    }

    onChanged();

    return this;

  }

  /**

   * Merges the field from another field.

   *

   * @param value the value to merge from

   * @return the builder

   */

  public SingleFieldBuilder<MType, BType, IType> mergeFrom(

      MType value) {

    if (builder == null && message == message.getDefaultInstanceForType()) {

      message = value;

    } else {

      getBuilder().mergeFrom(value);

    }

    onChanged();

    return this;

  }

  /**

   * Clears the value of the field.

   *

   * @return the builder

   */

  @SuppressWarnings("unchecked")

  public SingleFieldBuilder<MType, BType, IType> clear() {

    message = (MType) (message != null ?

        message.getDefaultInstanceForType() :

        builder.getDefaultInstanceForType());

    if (builder != null) {

      builder.dispose();

      builder = null;

    }

    onChanged();

    return this;

  }

  /**

   * Called when a the builder or one of its nested children has changed

   * and any parent should be notified of its invalidation.

   */

  private void onChanged() {

    // If builder is null, this is the case where onChanged is being called

    // from setMessage or clear.

    if (builder != null) {

      message = null;

    }

    if (isClean && parent != null) {

      parent.markDirty();

      // Don't keep dispatching invalidations until build is called again.

      isClean = false;

    }

  }

  //@Override (Java 1.6 override semantics, but we must support 1.5)

  public void markDirty() {

    onChanged();

  }

}