<commit_before>/*
 * Copyright (c) 2008-2017 Haulmont.
 *
 * 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.haulmont.cuba.gui.model;

import com.haulmont.bali.events.Subscription;
import com.haulmont.cuba.core.entity.Entity;
import com.haulmont.cuba.core.global.CommitContext;
import com.haulmont.cuba.core.global.EntitySet;
import com.haulmont.cuba.gui.screen.InstallSubject;
import com.haulmont.cuba.gui.screen.Subscribe;

import javax.annotation.Nullable;
import java.util.Collection;
import java.util.EventObject;
import java.util.Set;
import java.util.function.Consumer;
import java.util.function.Function;

/**
 * Interface for tracking changes in entities loaded to the client tier.
 * <p>
 * Within {@code DataContext}, an entity with the given identifier is represented by a single object instance, no matter
 * where and how many times it is used in object graphs.
 */
@InstallSubject("commitDelegate")
public interface DataContext {

    /**
     * Returns an entity instance by its class and id.
     * @return entity instance or null if there is no such entity in the context
     */
    @Nullable
    <T extends Entity<K>, K> T find(Class<T> entityClass, K entityId);

    /**
     * Returns the instance of entity with the same id if it exists in this context.
     * @return entity instance or null if there is no such entity in the context
     */
    @Nullable
    <T extends Entity> T find(T entity);

    /**
     * Returns true if the context contains the given entity (distinguished by its class and id).
     */
    boolean contains(Entity entity);

    /**
     * Merge the given entity into the context. The whole object graph with all references will be merged.
     * <p>
     * If an entity with the same identifier already exists in the context, the passed entity state is copied into
     * it and the existing instance is returned. Otherwise, a copy of the passed instance is registered in the context
     * and returned.
     * <p>
     * WARNING: It's very important to continue work with the returned value because it is always a different object instance.
     * The only case when you get the same instance is if it was previously returned from the same context as a
     * result of {@link #find(Class, Object)} or {@code merge()}.
     *
     * @return the instance which is tracked by the context
     */
    <T extends Entity> T merge(T entity);

    /**
     * Merge the given entities into the context. The whole object graph for each element of the collection with all
     * references will be merged.
     * <p>
     * For each element, if an entity with the same identifier already exists in the context, the passed entity state is
     * copied into it and the existing instance is added to the returned set. Otherwise, a copy of the passed instance
     * is registered in the context and added to the returned set.
     * <p>
     * WARNING: It's very important to continue work with instances from the returned set because they are always different
     * object instances. The only case when you get the same instance is if it was previously returned from the same
     * context as a result of {@link #find(Class, Object)} or {@code merge()}.
     *
     * @return set of instances tracked by the context
     * @see #merge(Entity)
     */
    EntitySet merge(Collection<? extends Entity> entities);

    /**
     * Removes the entity from the context and registers it as deleted. The entity will be removed from the data store
     * upon subsequent call to {@link #commit()}.
     * <p>
     * If the given entity is not in the context, nothing happens.
     */
    void remove(Entity entity);

    /**
     * Removes the entity from the context so the context stops tracking it.
     * <p>
     * If the given entity is not in the context, nothing happens.
     */
    void evict(Entity entity);

    /**
     * Creates an entity instance and merge it into the context.
     * <p>
     * Same as:
     * <pre>
     * Foo foo = dataContext.merge(metadata.create(Foo.class));
     * </pre>
     * @param entityClass entity class
     * @return a new instance which is tracked by the context
     */<commit_msg>Add @CheckReturnValue to DataContext.merge() #1985<commit_after>/*
 * Copyright (c) 2008-2017 Haulmont.
 *
 * 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.haulmont.cuba.gui.model;

import com.haulmont.bali.events.Subscription;
import com.haulmont.cuba.core.entity.Entity;
import com.haulmont.cuba.core.global.CommitContext;
import com.haulmont.cuba.core.global.EntitySet;
import com.haulmont.cuba.gui.screen.InstallSubject;
import com.haulmont.cuba.gui.screen.Subscribe;

import javax.annotation.CheckReturnValue;
import javax.annotation.Nullable;
import java.util.Collection;
import java.util.EventObject;
import java.util.Set;
import java.util.function.Consumer;
import java.util.function.Function;

/**
 * Interface for tracking changes in entities loaded to the client tier.
 * <p>
 * Within {@code DataContext}, an entity with the given identifier is represented by a single object instance, no matter
 * where and how many times it is used in object graphs.
 */
@InstallSubject("commitDelegate")
public interface DataContext {

    /**
     * Returns an entity instance by its class and id.
     * @return entity instance or null if there is no such entity in the context
     */
    @Nullable
    <T extends Entity<K>, K> T find(Class<T> entityClass, K entityId);

    /**
     * Returns the instance of entity with the same id if it exists in this context.
     * @return entity instance or null if there is no such entity in the context
     */
    @Nullable
    <T extends Entity> T find(T entity);

    /**
     * Returns true if the context contains the given entity (distinguished by its class and id).
     */
    boolean contains(Entity entity);

    /**
     * Merge the given entity into the context. The whole object graph with all references will be merged.
     * <p>
     * If an entity with the same identifier already exists in the context, the passed entity state is copied into
     * it and the existing instance is returned. Otherwise, a copy of the passed instance is registered in the context
     * and returned.
     * <p>
     * WARNING: It's very important to continue work with the returned value because it is always a different object instance.
     * The only case when you get the same instance is if it was previously returned from the same context as a
     * result of {@link #find(Class, Object)} or {@code merge()}.
     *
     * @return the instance which is tracked by the context
     */
    @CheckReturnValue
    <T extends Entity> T merge(T entity);

    /**
     * Merge the given entities into the context. The whole object graph for each element of the collection with all
     * references will be merged.
     * <p>
     * For each element, if an entity with the same identifier already exists in the context, the passed entity state is
     * copied into it and the existing instance is added to the returned set. Otherwise, a copy of the passed instance
     * is registered in the context and added to the returned set.
     * <p>
     * WARNING: It's very important to continue work with instances from the returned set because they are always different
     * object instances. The only case when you get the same instance is if it was previously returned from the same
     * context as a result of {@link #find(Class, Object)} or {@code merge()}.
     *
     * @return set of instances tracked by the context
     * @see #merge(Entity)
     */
    @CheckReturnValue
    EntitySet merge(Collection<? extends Entity> entities);

    /**
     * Removes the entity from the context and registers it as deleted. The entity will be removed from the data store
     * upon subsequent call to {@link #commit()}.
     * <p>
     * If the given entity is not in the context, nothing happens.
     */
    void remove(Entity entity);

    /**
     * Removes the entity from the context so the context stops tracking it.
     * <p>
     * If the given entity is not in the context, nothing happens.
     */
    void evict(Entity entity);

    /**
     * Creates an entity instance and merge it into the context.
     * <p>
     * Same as:
     * <pre>
     * Foo foo = dataContext.merge(metadata.create(Foo.class));
     * </pre>
     * @param entityClass entity class
     * @return a new instance which is tracked by the context
     */
{'fraction_non_alphanumeric': 0.07625065824117956, 'fraction_numerical': 0.0029489204844655083, 'mean_word_length': 3.0755364806866954, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3870231', 'n_tokens_mistral': 2484, 'n_tokens_neox': 2418, 'n_words': 1214}