<commit_before>/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see http://www.gnu.org/licenses/
 */
package org.phenotips.entities;

import org.xwiki.bridge.DocumentModelBridge;
import org.xwiki.component.annotation.Role;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.stability.Unstable;

import java.util.Collection;

/**
 * API that provides access for a specific type of entity, with support for simple CRUD operations. No access rights are
 * checked here.
 *
 * @param <E> the type of entities handled by this manager
 * @version $Id$
 * @since 1.3M2
 */
@Unstable("New API introduced in 1.3")
@Role
public interface PrimaryEntityManager<E extends PrimaryEntity>
{
    /**
     * Creates and returns a new empty entity, setting the currently logged in user as the creator.
     *
     * @return the created entity, or {@code null} in case of errors
     */
    E create();

    /**
     * Creates and returns a new empty entity, setting the given principal as the creator.
     *
     * @param creator a reference to the document representing a principal (a user or a group) which will be set as the
     *            creator for the created entity
     * @return the created entity, or {@code null} in case of errors
     */
    @Unstable("The type of the parameter will be replaced by Principal, once the principals module is implemented")
    E create(DocumentReference creator);

    /**
     * Retrieves an {@link PrimaryEntity entity} by its {@link PrimaryEntity#getId() internal PhenoTips identifier}.
     *
     * @param id the {@link PrimaryEntity#getId() entity identifier}, i.e. the serialized document reference
     * @return the requested entity
     * @throws IllegalArgumentException if the requested entity does not exist or is not really a type of the entity
     *             requested
     */
    E get(String id);

    /**
     * Retrieves an {@link PrimaryEntity entity} from the specified document.
     *
     * @param reference reference of the {@link PrimaryEntity#getDocument() document where the entity is stored}<commit_msg>PT-2640: Add generic APIs for working with primary entities and entity groups Added a method for getting the preferred space where entities are stored<commit_after>/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see http://www.gnu.org/licenses/
 */
package org.phenotips.entities;

import org.xwiki.bridge.DocumentModelBridge;
import org.xwiki.component.annotation.Role;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.model.reference.EntityReference;
import org.xwiki.stability.Unstable;

import java.util.Collection;

/**
 * API that provides access for a specific type of entity, with support for simple CRUD operations. No access rights are
 * checked here.
 *
 * @param <E> the type of entities handled by this manager
 * @version $Id$
 * @since 1.3M2
 */
@Unstable("New API introduced in 1.3")
@Role
public interface PrimaryEntityManager<E extends PrimaryEntity>
{
    /**
     * Gets the space where entities of this type are stored in.
     *
     * @return a local space reference, without the wiki name
     */
    EntityReference getDataSpace();

    /**
     * Creates and returns a new empty entity, setting the currently logged in user as the creator.
     *
     * @return the created entity, or {@code null} in case of errors
     */
    E create();

    /**
     * Creates and returns a new empty entity, setting the given principal as the creator.
     *
     * @param creator a reference to the document representing a principal (a user or a group) which will be set as the
     *            creator for the created entity
     * @return the created entity, or {@code null} in case of errors
     */
    @Unstable("The type of the parameter will be replaced by Principal, once the principals module is implemented")
    E create(DocumentReference creator);

    /**
     * Retrieves an {@link PrimaryEntity entity} by its {@link PrimaryEntity#getId() internal PhenoTips identifier}.
     *
     * @param id the {@link PrimaryEntity#getId() entity identifier}, i.e. the serialized document reference
     * @return the requested entity
     * @throws IllegalArgumentException if the requested entity does not exist or is not really a type of the entity
     *             requested
     */
    E get(String id);

    /**
     * Retrieves an {@link PrimaryEntity entity} from the specified document.
     *
     * @param reference reference of the {@link PrimaryEntity#getDocument() document where the entity is stored}
{'fraction_non_alphanumeric': 0.07053872053872054, 'fraction_numerical': 0.0026936026936026937, 'mean_word_length': 3.3877400295420976, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, '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': '2897194', 'n_tokens_mistral': 1476, 'n_tokens_neox': 1458, 'n_words': 740}