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 import org.onap.policy.apex.model.basicmodel.concepts.AxArtifactKey;
  25 import org.onap.policy.apex.model.basicmodel.concepts.AxConcept;
  26 import org.onap.policy.apex.model.contextmodel.concepts.AxContextAlbum;
  27
  28 /**
  29  * The Interface ContextAlbum is implemented by all classes that manage context in Apex. Context
  30  * albums may store context in memory, on disk, in a repository or in a mechanism such as a
  31  * distributed map.
  32  *
  33  * <p>A context album uses plugins to handle its context schemas, its distribution, its locking, and
  34  * its persistence.
  35  *
  36  * <p>The schema that defines the items in a context album is interpreted by a plugin that implements
  37  * the {@link SchemaHelper} interface. The schema helper uses the schema definition to provide new
  38  * instances for a context album. By default, context albums use Java schemas.
  39  *
  40  * <p>Context albums may be shared across an arbitrary number of JVMs using a distribution mechanism.
  41  * Apex context distributed context albums using plugins that implement the {@link Distributor}
  42  * interface. By default, context albums use JVM local distribution, that is context albums are only
  43  * available in a single JVM
  44  *
  45  * <p>Items in a context album may be locked across all distributed instances of an album. Apex locks
  46  * instances on context albums using the distributed locking mechanism in a plugin that implements
  47  * the {@link LockManager} interface. By default, context albums use Java locking local to a single
  48  * JVM on each context album instance.
  49  *
  50  * <p>Context albums may be persisted to disk, database, or any other repository. Apex persists context
  51  * albums using the persistence mechanism in a plugin that implements the {@link Persistor}
  52  * interface. By default, context albums use a dummy persistor plugin that does not persist context
  53  * albums.
  54  *
  55  * @author Liam Fallon (liam.fallon@ericsson.com)
  56  */
  57 public interface ContextAlbum extends Map<String, Object> {
  58     /**
  59      * Gets the key of the context album instance.
  60      *
  61      * @return the key
  62      */
  63     AxArtifactKey getKey();
  64
  65     /**
  66      * Gets the name of the context album instance.
  67      *
  68      * @return the name
  69      */
  70     String getName();
  71
  72     /**
  73      * Get the current context album with values.
  74      *
  75      * @return the current context runtime values
  76      */
  77     AxContextAlbum getAlbumDefinition();
  78
  79     /**
  80      * Get the schema helper for the technology that is handling the schema for this album.
  81      *
  82      * @return the schema helper
  83      */
  84     SchemaHelper getSchemaHelper();
  85
  86     /**
  87      * Place a read lock on a key in this album across the entire cluster.
  88      *
  89      * @param key The key to lock
  90      * @throws ContextException on locking errors
  91      */
  92     void lockForReading(String key) throws ContextException;
  93
  94     /**
  95      * Place a write lock on a key in this album across the entire cluster.
  96      *
  97      * @param key The key to lock
  98      * @throws ContextException on locking errors
  99      */
 100     void lockForWriting(String key) throws ContextException;
 101
 102     /**
 103      * Release the the read lock on a key in this album across the entire cluster.
 104      *
 105      * @param key The key to unlock
 106      * @throws ContextException on locking errors
 107      */
 108     void unlockForReading(String key) throws ContextException;
 109
 110     /**
 111      * Release the the write lock on a key in this album across the entire cluster.
 112      *
 113      * @param key The key to unlock
 114      * @throws ContextException on locking errors
 115      */
 116     void unlockForWriting(String key) throws ContextException;
 117
 118     /**
 119      * Get the stack of artifact keys currently using this context item.
 120      *
 121      * @return the keys of the artifacts using the context album at the moment
 122      */
 123     AxConcept[] getUserArtifactStack();
 124
 125     /**
 126      * Set the stack of artifact keys currently using this context item.
 127      *
 128      * @param userArtifactStack the keys of the artifacts using the context album at the moment
 129      */
 130     void setUserArtifactStack(AxConcept[] userArtifactStack);
 131
 132     /**
 133      * Flush the context album to the distribution and persistence mechanism.
 134      *
 135      * @throws ContextException On context flush errors
 136      */
 137     void flush() throws ContextException;
 138 }