| /******************************************************************************** |
| * Copyright (c) 2015-2019 Contributors to the Eclipse Foundation |
| * |
| * See the NOTICE file(s) distributed with this work for additional |
| * information regarding copyright ownership. |
| * |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v. 2.0 which is available at |
| * http://www.eclipse.org/legal/epl-2.0. |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| ********************************************************************************/ |
| |
| package org.eclipse.mdm.api.base; |
| |
| import java.util.Collection; |
| import java.util.Collections; |
| import java.util.List; |
| import java.util.Map; |
| import java.util.Optional; |
| |
| import org.eclipse.mdm.api.base.massdata.ReadRequest; |
| import org.eclipse.mdm.api.base.model.ContextDescribable; |
| import org.eclipse.mdm.api.base.model.ContextRoot; |
| import org.eclipse.mdm.api.base.model.ContextType; |
| import org.eclipse.mdm.api.base.model.Entity; |
| import org.eclipse.mdm.api.base.model.Environment; |
| import org.eclipse.mdm.api.base.model.MeasuredValues; |
| import org.eclipse.mdm.api.base.model.Measurement; |
| import org.eclipse.mdm.api.base.model.TestStep; |
| import org.eclipse.mdm.api.base.model.User; |
| import org.eclipse.mdm.api.base.query.DataAccessException; |
| |
| /** |
| * Provides business layer CRUD operations and services (CREATE, READ, UPDATE, |
| * INSERT). |
| * |
| * @since 1.0.0 |
| * @author Viktor Stoehr, Gigatronik Ingolstadt GmbH |
| * @author Sebastian Dirsch, Gigatronik Ingolstadt GmbH |
| */ |
| public interface BaseEntityManager { |
| |
| /** |
| * Returns the {@link Environment} this entity manager is connected to. |
| * |
| * @return The {@code Environment} is returned. |
| * @throws DataAccessException Thrown if unable to retrieve the {@code |
| * Environment} . |
| */ |
| Environment loadEnvironment() throws DataAccessException; |
| |
| /** |
| * Returns the {@link User} which was used to connect to the underlying data |
| * source. |
| * |
| * @return {@code Optional} is empty if the data source connection is user |
| * independent, which is implementation specific. |
| * @throws DataAccessException Thrown if unable to retrieve the {@code User}. |
| */ |
| default Optional<User> loadLoggedOnUser() throws DataAccessException { |
| return Optional.empty(); |
| } |
| |
| /** |
| * Loads the entity identified by given entity class and its instance ID. |
| * |
| * @param <T> The desired type. |
| * @param entityClass Type of the returned entity. |
| * @param instanceID The instance ID. |
| * @return The entity with given instance ID is returned. |
| * @throws DataAccessException Thrown if unable to retrieve the entity. |
| */ |
| default <T extends Entity> T load(Class<T> entityClass, String instanceID) throws DataAccessException { |
| List<T> entities = load(entityClass, Collections.singletonList(instanceID)); |
| if (entities.size() != 1) { |
| throw new DataAccessException("Failed to load entity by instance ID."); |
| } |
| return entities.get(0); |
| } |
| |
| /** |
| * Loads the entities identified by given entity class and its instance IDs. |
| * |
| * @param <T> The desired type. |
| * @param entityClass Type of the returned entities. |
| * @param instanceIDs The instance IDs to load. If a instance ID does not exist, |
| * it is ignored. |
| * @return Entities are returned in a list. |
| * @throws DataAccessException Thrown if unable to retrieve the entities. |
| */ |
| <T extends Entity> List<T> load(Class<T> entityClass, Collection<String> instanceIDs) throws DataAccessException; |
| |
| /** |
| * Loads all available entities of given type. This method is useful while |
| * working with types whose amount is known to be fairly small (e.g.: |
| * {@code Unit}, {@code Quantity}, etc.). If a type is given where thousand |
| * instances exist (e.g.: {@code Test}) the behavior of this method is |
| * implementation specific. The following invocation might take its time to |
| * complete or even result in an exception as soon as too many results are |
| * found: |
| * |
| * <pre> |
| * { |
| * @code |
| * List<Test> tests = entityManager.loadAll(Test.class); |
| * } |
| * </pre> |
| * |
| * @param <T> The desired type. |
| * @param entityClass Type of the returned entities. |
| * @return Entities are returned in a {@code List}. |
| * @throws DataAccessException Thrown if unable to retrieve the entities. |
| * @see #loadAll(Class, String) |
| */ |
| default <T extends Entity> List<T> loadAll(Class<T> entityClass) throws DataAccessException { |
| return loadAll(entityClass, "*"); |
| } |
| |
| /** |
| * Loads all available entities of given type whose name fulfills the given |
| * pattern. This method is useful while working with types whose amount is known |
| * to be fairly small (e.g.: {@code Unit}, {@code Quantity}, etc.). If a type is |
| * given where thousand instances exist (e.g.: {@code Test}) the behavior of |
| * this method is implementation specific. The following invocation might take |
| * its time to complete or even result in an exception as soon as too many |
| * results are found: |
| * |
| * <pre> |
| * { |
| * @code |
| * // retrieve all tests whose name starts with 'Example' |
| * List<Test> tests = entityManager.loadAll(Test.class, "Example*"); |
| * } |
| * </pre> |
| * |
| * @param <T> The desired type. |
| * @param entityClass Type of the returned entities. |
| * @param pattern Is always case sensitive and may contain wildcard |
| * characters as follows: "?" for one matching character and |
| * "*" for a sequence of matching characters. |
| * @return Matched entities are returned in a {@code List}. |
| * @throws DataAccessException Thrown if unable to retrieve the entities. |
| * @see #loadAll(Class) |
| */ |
| <T extends Entity> List<T> loadAll(Class<T> entityClass, String pattern) throws DataAccessException; |
| |
| /** |
| * Loads the parent entity for given child. Each modeled entity provides public |
| * fields for available parent entity types e.g.: |
| * |
| * <pre> |
| * { |
| * @code |
| * Optional<Test> parentTest = entityManager.loadParent(testStep, TestStep.PARENT_TYPE_TEST); |
| * } |
| * </pre> |
| * |
| * @param <T> The desired parent type. |
| * @param child The child entity. |
| * @param entityClass The desired parent entity type. |
| * @return {@code Optional} is empty if parent entity could not be found. |
| * @throws DataAccessException Thrown if unable to retrieve parent entity. |
| */ |
| <T extends Entity> Optional<T> loadParent(Entity child, Class<T> entityClass) throws DataAccessException; |
| |
| /** |
| * Loads all related children of given type for given parent entity. Each |
| * modeled entity provides public fields for available child entity types e.g.: |
| * |
| * <pre> |
| * { |
| * @code |
| * List<Channel> channels = entityManager.loadChildren(measurement, Measurement.CHILD_TYPE_CHANNEL); |
| * } |
| * </pre> |
| * |
| * @param <T> The desired child type. |
| * @param parent The parent entity. |
| * @param entityClass The desired child entity type. |
| * @return Related child entities are returned in a {@code List}. |
| * @throws DataAccessException Thrown if unable to retrieve the children. |
| * @see #loadChildren(Entity, Class, String) |
| */ |
| default <T extends Entity> List<T> loadChildren(Entity parent, Class<T> entityClass) throws DataAccessException { |
| return loadChildren(parent, entityClass, "*"); |
| } |
| |
| /** |
| * Loads all related children of given type for given parent entity whose name |
| * fulfills the given pattern. Each modeled entity provides public fields for |
| * available child entity types e.g.: |
| * |
| * <pre> |
| * { |
| * @code |
| * List<TestStep> testSteps = entityManager.loadChildren(test, Test.CHILD_TYPE_TESTSTEP, "Example*"); |
| * } |
| * </pre> |
| * |
| * @param <T> The desired child type. |
| * @param parent The parent entity. |
| * @param entityClass The desired child entity type. |
| * @param pattern Is always case sensitive and may contain wildcard |
| * characters as follows: "?" for one matching character and |
| * "*" for a sequence of matching characters. |
| * @return Matched child entities are returned in a {@code List}. |
| * @throws DataAccessException Thrown if unable to retrieve the children. |
| * @see #loadChildren(Entity, Class) |
| */ |
| <T extends Entity> List<T> loadChildren(Entity parent, Class<T> entityClass, String pattern) |
| throws DataAccessException; |
| |
| /** |
| * Queries available {@link ContextType} for given {@link ContextDescribable}. |
| * |
| * @param contextDescribable Either a {@link TestStep} or a {@link Measurement} |
| * @return {@code List} contains the {@code ContextType} of each referenced |
| * {@link ContextRoot}. |
| * @throws DataAccessException Thrown if unable to query the available |
| * {@code ContextType}s. |
| */ |
| List<ContextType> loadContextTypes(ContextDescribable contextDescribable) throws DataAccessException; |
| |
| /** |
| * Loads the requested {@link ContextRoot}s for given |
| * {@link ContextDescribable}. |
| * |
| * @param contextDescribable Either a {@link TestStep} or {@link Measurement}. |
| * @param contextTypes The requested context types. If omitted, all types |
| * are be loaded. |
| * @return The ordered contexts for given {@code TestStep} or the measured ones |
| * for {@code Measurement} are returned in a {@code Map}. |
| * @throws DataAccessException Thrown if unable to retrieve the {@code |
| * ContextRoot} s. |
| * @see ContextType |
| */ |
| Map<ContextType, ContextRoot> loadContexts(ContextDescribable contextDescribable, ContextType... contextTypes) |
| throws DataAccessException; |
| |
| /** |
| * @param entity The entity |
| * @param relationName The name of the relation, which entities should be |
| * loaded. |
| * @param relatedClass Class of the related entities. |
| * @return The related entities for the given {@link Entity} and relationName |
| */ |
| <T extends Entity> List<T> loadRelatedEntities(Entity entity, String relationName, Class<T> relatedClass); |
| |
| /** |
| * Retrieves the {@link MeasuredValues} as specified by the given |
| * {@link ReadRequest}. |
| * |
| * @param readRequest Provides all required informations to process the request. |
| * @return Returns the {@code MeasuredValues} in a {@code List} as specified in |
| * the given {@code ReadRequest}. |
| * @throws DataAccessException Thrown if unable to access the measured values. |
| */ |
| List<MeasuredValues> readMeasuredValues(ReadRequest readRequest) throws DataAccessException; |
| |
| /** |
| * Creates a new {@link Transaction} for modifying access. |
| * |
| * @return A new {@code Transaction} is returned. |
| * @throws DataAccessException Thrown if unable to create a new |
| * {@code Transaction}. |
| */ |
| Transaction startTransaction() throws DataAccessException; |
| |
| /** |
| * Returns links to the given entities in the data store. The format of the |
| * links is adapter specific and depends on the underlying data store. The links |
| * can be used by the client to directly access the entities by bypassing the |
| * MDM API, if the client is capable of accessing the adapters data store. The |
| * client can invoke {@link BaseApplicationContext#getAdapterType()} to get the |
| * type of the adapter. |
| * |
| * @param entities the Entities for which the links are retrieved |
| * @return the links to the given entities in the data store abstracted by the |
| * current adapter. The map contains the requested entities as keys and |
| * the corresponding links as values. |
| */ |
| Map<Entity, String> getLinks(Collection<Entity> entities); |
| } |