001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.api.service.collections;
015
016import org.gbif.api.model.collections.CollectionEntity;
017import org.gbif.api.model.collections.MasterSourceMetadata;
018import org.gbif.api.service.registry.CommentService;
019import org.gbif.api.service.registry.MachineTagService;
020import org.gbif.api.service.registry.PrimaryIdentifierService;
021import org.gbif.api.service.registry.TagService;
022import org.gbif.api.vocabulary.collections.Source;
023
024import java.util.List;
025import java.util.Optional;
026import java.util.UUID;
027
028import javax.validation.Valid;
029import javax.validation.constraints.NotNull;
030
031public interface CollectionEntityService<T extends CollectionEntity>
032    extends CrudService<T>,
033        PrimaryIdentifierService,
034        TagService,
035        MachineTagService,
036        CommentService,
037        ContactService,
038        OccurrenceMappingService {
039
040  /** Replaces a entity with another. The entity replaced is also deleted. */
041  void replace(UUID entityToReplaceKey, UUID replacementKey);
042
043  /**
044   * Adds {@link MasterSourceMetadata} to an entity.
045   *
046   * @param targetEntityKey key of the entity to add the metadata to
047   * @param masterSourceMetadata metadata to add
048   * @return key of the created metadata
049   */
050  int addMasterSourceMetadata(UUID targetEntityKey, MasterSourceMetadata masterSourceMetadata);
051
052  /**
053   * Removes the {@link MasterSourceMetadata} from an entity.
054   *
055   * @param targetEntityKey key of the entity whose metadata will be deleted
056   */
057  void deleteMasterSourceMetadata(UUID targetEntityKey);
058
059  /**
060   * Returns the {@link MasterSourceMetadata} of the entity.
061   *
062   * @param targetEntityKey key of the entity
063   * @return {@link MasterSourceMetadata}
064   */
065  MasterSourceMetadata getMasterSourceMetadata(@NotNull UUID targetEntityKey);
066
067  /**
068   * Finds the collection entity whose master data metadata matches with the parameters received.
069   *
070   * @param source source of the metadata
071   * @param sourceId source Id of the metadata
072   * @return {@link Optional} with the collection entity found
073   */
074  List<T> findByMasterSource(Source source, String sourceId);
075
076  /**
077   * Updates an existing entity.
078   *
079   * @param entity that will replace the existing entity.
080   * @param lockFields indicates if fields that come from an external master source has to be
081   *     locked.
082   */
083  void update(@NotNull @Valid T entity, boolean lockFields);
084}