context/context-management/src/main/java/org/onap/policy/apex/context/ContextAlbum.java

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
   4  * ================================================================================
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *      http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  * SPDX-License-Identifier: Apache-2.0
  18  * ============LICENSE_END=========================================================
  19  */
  20
  21 package org.onap.policy.apex.context;
  22
  23 import java.util.Map;
  24
  25 import org.onap.policy.apex.model.basicmodel.concepts.AxArtifactKey;
  26 import org.onap.policy.apex.model.basicmodel.concepts.AxConcept;
  27 import org.onap.policy.apex.model.contextmodel.concepts.AxContextAlbum;
  28
  29 /**
  30  * The Interface ContextAlbum is implemented by all classes that manage context in Apex. Context
  31  * albums may store context in memory, on disk, in a repository or in a mechanism such as a
  32  * distributed map.
  33  *
  34  * <p>A context album uses plugins to handle its context schemas, its distribution, its locking, and
  35  * its persistence.
  36  *
  37  * <p>The schema that defines the items in a context album is interpreted by a plugin that implements
  38  * the {@link SchemaHelper} interface. The schema helper uses the schema definition to provide new
  39  * instances for a context album. By default, context albums use Java schemas.
  40  *
  41  * <p>Context albums may be shared across an arbitrary number of JVMs using a distribution mechanism.
  42  * Apex context distributed context albums using plugins that implement the {@link Distributor}
  43  * interface. By default, context albums use JVM local distribution, that is context albums are only
  44  * available in a single JVM
  45  *
  46  * <p>Items in a context album may be locked across all distributed instances of an album. Apex locks
  47  * instances on context albums using the distributed locking mechanism in a plugin that implements
  48  * the {@link LockManager} interface. By default, context albums use Java locking local to a single
  49  * JVM on each context album instance.
  50  *
  51  * <p>Context albums may be persisted to disk, database, or any other repository. Apex persists context
  52  * albums using the persistence mechanism in a plugin that implements the {@link Persistor}
  53  * interface. By default, context albums use a dummy persistor plugin that does not persist context
  54  * albums.
  55  *
  56  * @author Liam Fallon (liam.fallon@ericsson.com)
  57  */
  58 public interface ContextAlbum extends Map<String, Object> {
  59     /**
  60      * Gets the key of the context album instance.
  61      *
  62      * @return the key
  63      */
  64     AxArtifactKey getKey();
  65
  66     /**
  67      * Gets the name of the context album instance.
  68      *
  69      * @return the name
  70      */
  71     String getName();
  72
  73     /**
  74      * Get the current context album with values.
  75      *
  76      * @return the current context runtime values
  77      */
  78     AxContextAlbum getAlbumDefinition();
  79
  80     /**
  81      * Get the schema helper for the technology that is handling the schema for this album.
  82      *
  83      * @return the schema helper
  84      */
  85     SchemaHelper getSchemaHelper();
  86
  87     /**
  88      * Place a read lock on a key in this album across the entire cluster.
  89      *
  90      * @param key The key to lock
  91      * @throws ContextException on locking errors
  92      */
  93     void lockForReading(String key) throws ContextException;
  94
  95     /**
  96      * Place a write lock on a key in this album across the entire cluster.
  97      *
  98      * @param key The key to lock
  99      * @throws ContextException on locking errors
 100      */
 101     void lockForWriting(String key) throws ContextException;
 102
 103     /**
 104      * Release the the read lock on a key in this album across the entire cluster.
 105      *
 106      * @param key The key to unlock
 107      * @throws ContextException on locking errors
 108      */
 109     void unlockForReading(String key) throws ContextException;
 110
 111     /**
 112      * Release the the write lock on a key in this album across the entire cluster.
 113      *
 114      * @param key The key to unlock
 115      * @throws ContextException on locking errors
 116      */
 117     void unlockForWriting(String key) throws ContextException;
 118
 119     /**
 120      * Get the stack of artifact keys currently using this context item.
 121      *
 122      * @return the keys of the artifacts using the context album at the moment
 123      */
 124     AxConcept[] getUserArtifactStack();
 125
 126     /**
 127      * Set the stack of artifact keys currently using this context item.
 128      *
 129      * @param userArtifactStack the keys of the artifacts using the context album at the moment
 130      */
 131     void setUserArtifactStack(AxConcept[] userArtifactStack);
 132
 133     /**
 134      * Flush the context album to the distribution and persistence mechanism.
 135      *
 136      * @throws ContextException On context flush errors
 137      */
 138     void flush() throws ContextException;
 139 }