com.swirlds.common.FastCopyable Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of swirlds-common Show documentation

Swirlds is a software platform designed to build fully-distributed applications that harness the power of the cloud without servers. Now you can develop applications with fairness in decision making, speed, trust and reliability, at a fraction of the cost of traditional server-based platforms.

There is a newer version: 0.56.6

Show newest version

/*
 * Copyright (C) 2016-2024 Hedera Hashgraph, LLC
 *
 * 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.swirlds.common;

import com.swirlds.base.state.Mutable;

/**
 * An interface for classes that can be copied and serialized in a way specific to the Swirlds platform. If a class
 * implements the FastCopyable interface, then it should use a copy-on-write strategy so that calls to {@link #copy}
 * make virtual copies almost instantaneously. See the documentation for these methods for the details on what they
 * should do, and how they differ from the usual Java copy and
 * serialize methods.
 */
public interface FastCopyable extends Copyable, Mutable, Releasable {

    /**
     * If a class ExampleClass implements the FastCopyable interface, and an object x is of class
     * ExampleClass, then x.copy() instantiates and returns a new ExampleClass object containing the same
     * data as x. This should be a deep clone, not shallow. So if x contains references to other objects, it
     * should do something like copy() on them, too, rather than just copying the reference.
     * 
     * Furthermore, the copy operation should be fast, at the possible cost of making reads and writes
     * slower (such as by using some kind of copy-on-write mechanism).
     * This method causes the object to become immutable and returns a mutable copy.
     * If the object is already immutable:
     * 

     *     it can throw an MutabilityException
     *     or it can implement a slow, deep copy that returns a mutable object 
     * 
     *
     * Either behavior is fine, but each implementation should document which behavior it has chosen.
     * By the default, the first implementation is assumed.
     *
     * If a FastCopyable object extends {@link com.swirlds.common.crypto.Hashable} then under no circumstances should
     * the hash be copied by this method.
     *
     * It is strongly suggested that each implementing class override the return type of this method to its self
     * type. So if class Foo extends FastCopyable then Foo's copy signature should look like "public Foo copy()".
     *
     * @return the new copy that was made
     */
    @Override
     T copy();

    /**
     * Determines if an object/copy is immutable or not.
     * Only the most recent copy must be mutable.
     *
     * @return Whether the object is immutable or not
     */
    @Override
    default boolean isImmutable() {
        return true;
    }
}