Context.java

/*
 * Copyright (c) 2007-2026 MetaSolutions AB
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.entrystore;

import java.net.URI;
import java.util.Date;
import java.util.Map;
import java.util.Set;


/**
 * A Context keeps track of a set of {@link Entry}s, at a minimum it provides default
 * ownership according to the access control in it's {@link Entry}.
 *
 * All the methods may throw {@link AuthorizationException} if the user has insufficient
 * rights. If something else goes wrong in a method a {@link org.entrystore.repository.RepositoryException} is
 * thrown instead.
 * 
 * @author matthias
 *
 */
public interface Context extends Resource{
	
	//***********************************************************************//
	// Methods for creating and removing resources, links and references     //
	// in this context.                                                      //
	//***********************************************************************//
	/**
	 * Creates a Entry where the {@link EntryType} is {@link EntryType#Local}.
	 * The creation is allowed if: 
	 * <ul><li>The user has write access to the context. Or</li>
	 * <li>A list is provided in the context where the user has write access.</li></ul>
	 * In the former case the new resources access control will be decided by the 
	 * context, in the latter by the list.
	 * @param entryId, optional value to use for id for the new entry.
	 * @param buiType, which builtin type to use. 
	 * @param repType, which representation type to use. Ignored if buiType is 
	 * anything else than None.
	 * @param listURI the list to add the resource to, or null if the resource
	 * should be created freely in the context.
	 * @return a {@link Entry} containing the resource, it's metadata, 
	 * and it's metametadata. Which exact subclass of resource used depends on the 
	 * {@link GraphType}.
	 * @see {@link GraphType}.
	 */
	Entry createResource(String entryId, GraphType buiType, ResourceType repType, URI listURI); // files, folders, persons

	/**
	 * Creates an Entry where the {@link EntryType} is {@link EntryType#Link}.
	 * The creation is allowed if: 
	 * <ul><li>The user has write access to the context. Or</li>
	 * <li>A list is provided in the context where the user has write access.</li></ul>
	 * In the former case the new link's access control will be decided by the 
	 * context, in the latter by the list.
	 * 
	 * @param entryId, optional value to use for id for the new entry.
	 * @param resourceURI any resource to link to, may be internal or external to the repository.
	 * @param listURI the list to add the link to, or null if the link
	 * should be created freely in the context.
	 * @return a {@link Entry} containing the metadata and metametadata for the link.
	 */
	Entry createLink(String entryId, URI resourceURI, URI listURI); // links to pages, bookmarks

	/**
	 * Creates an Entry where the {@link EntryType} is {@link EntryType#Reference}.
	 * The creation is allowed if: 
	 * <ul><li>The user has write access to the context. Or</li>
	 * <li>A list is provided in the context where the user has write access.</li></ul>
	 * In the former case the new reference's access control will be decided by the 
	 * context, in the latter by the list.
	 * 
	 * @param entryId, optional value to use for id for the new entry.
	 * @param resourceURI any resource to link to, may be internal or external to the repository.
	 * @param metadataURI the resources metadata that we intend to reference.
	 * @param listURI the list to add the reference to, or null if the reference
	 * should be created freely in the context.
	 * @return a {@link Entry} containing metametadata and potentially cached metadata 
	 * for the reference.
	 */
	Entry createReference(String entryId, URI resourceURI, URI metadataURI, URI listURI); // references
	
	Entry createLinkReference(String entryId, URI resourceURI, URI metadataURI, URI listURI); 

	//void move(URI entryUri, URI fromListURI, URI toListURI);
	
	/**
	 * @param entryURI the URI of the resource's metametadata to remove.
	 */
	void remove(URI entryURI);
	
	
	//***********************************************************************//
	// Retrieval methods for the different URIs of the Entry.                 //
	//***********************************************************************//
	/**
	 * @param entryId must be a unique identifier for an item in this context.
	 * @return the Entry with this identifier.
	 */
	Entry get(String entryId);
	
	/**
	 * Looks up an entry of this context only; {@link ContextManager#getEntry(URI)} is the repository-wide lookup.
	 *
	 * @param entryURI is the URI to the entry.
	 * @return the Entry of this context that has this entryURI, or null if there is none.
	 */
	Entry getByEntryURI(URI entryURI);

	/**
	 * Looks up the entries referencing an external metadata URI.
	 *
	 * <p>Served from an index built from the repository on first use, so the returned set is an
	 * independent snapshot: mutating it does not affect the context, and it does not reflect entries
	 * added or removed after the call. See {@link #isIndexComplete()} before deriving a destructive
	 * action or a persisted total from it.
	 *
	 * @param metadataURI is the URI to an external Metadata referenced by an item in this context.
	 * @return a set of Entries referencing this metadata, never null; empty if {@code metadataURI} is null.
	 * @throws org.entrystore.repository.RepositoryException if the index cannot be loaded.
	 */
	Set<Entry> getByExternalMdURI(URI metadataURI);

	/**
	 * Looks up the entries with a given resource URI. Index-backed and snapshot-returning; see
	 * {@link #getByExternalMdURI(URI)}.
	 *
	 * @param resourceURI is the URI to the resource for a set of entries in this context.
	 * @return a set of Entries that has this resourceURI, never null; empty if {@code resourceURI} is null.
	 * @throws org.entrystore.repository.RepositoryException if the index cannot be loaded.
	 */
	Set<Entry> getByResourceURI(URI resourceURI);

	/**
	 * Index-backed and snapshot-returning; see {@link #getByExternalMdURI(URI)}.
	 *
	 * @return the set of all resources managed in this context
	 * (each resource represented by its URI).
	 * @throws org.entrystore.repository.RepositoryException if the index cannot be loaded.
	 */
	Set<URI> getResources();

	/**
	 * Index-backed and snapshot-returning; see {@link #getByExternalMdURI(URI)}.
	 *
	 * @return the set of all entries managed in this context
	 * (each entry represented by its mmd URI).
	 * @throws org.entrystore.repository.RepositoryException if the index cannot be loaded.
	 */
	Set<URI> getEntries();

	/**
	 * Whether every statement in this context's index graph could be indexed.
	 *
	 * <p>False means the listings above are <em>short</em>: an entry exists that they do not name, because
	 * the statement naming it could not be parsed. Listing anyway is deliberate — refusing would make one
	 * malformed triple deny every read of the context, and repairing it requires reading the context — but
	 * a caller that deletes, purges or persists a total derived from a listing must check this first and
	 * refuse, or it will act on data it cannot see.
	 *
	 * <p>Refusing is only the right answer while the destructive step is still ahead of the check. A
	 * caller that has already destroyed something by the time it could ask — a rebuild that clears its
	 * target first, or a purge-then-import — must instead enumerate from the store, where the listing
	 * cannot be short, rather than skip its work on a short one and lose more than it saves.
	 *
	 * @return true when the index is known to be complete, which is also the answer for implementations
	 * that do not maintain one.
	 * @throws org.entrystore.repository.RepositoryException if the index cannot be loaded.
	 */
	default boolean isIndexComplete() {
		return true;
	}
	
	//***********************************************************************//
	// Administration methods, since we do not subclass the MetaMetadata     //
	// class, we have to provide context specific methods here instead.      //
	//***********************************************************************//
	/**
	 * If quota is exceeded new links and references are still allowed.
	 * 
	 * @return The quota in bytes, -1 means unlimited quota. 
	 * The quota limits only the amount of uploaded data, not the amount of metadata 
	 * or metametadata.
	 * 
	 * @see Quota
	 * @see Data
	 */
	long getQuota();
	
	/**
	 * @param quotaInBytes amount of quota in bytes.
	 * @see #getQuota()
	 */
	void setQuota(long quotaInBytes);

	/**
	 * @return Returns a boolean to depict whether the Context's quota defaults
	 *         to the system setting or whether it has been set manually.
	 */
	boolean hasDefaultQuota();

	/**
	 * Removes an eventually set Quota and returns the context's setting to
	 * using the system-wide set default quota.
	 */
	void removeQuota();
	
	/**
	 * @return The use amount of data in bytes (not percentage).
	 */
	long getQuotaFillLevel();
	
	/**
	 * This is a thread-safe method to manage the quota fill level.
	 * 
	 * @param bytes Bytes to add to the quota fill level.
	 */
	public void increaseQuotaFillLevel(long bytes) throws QuotaException;
	
	/**
	 * This is a thread-safe method to manage the quota fill level.
	 * 
	 * @param bytes Bytes to abstract from the quota fill level.
	 */
	public void decreaseQuotaFillLevel(long bytes);
	
	/**
	 * Initializes all the System Entries, i.e. with entryId 
	 * beginning with a '_'.
	 *
	 */
	void initializeSystemEntries();
	
	void reIndex();
	
	public Map<URI, DeletedEntryInfo> getDeletedEntries();
	
	public Map<URI, DeletedEntryInfo> getDeletedEntriesInRange(Date from, Date until);

	/**
	 * A context object may still exist even though the entry is removed from both repository
	 * and cache. Necessary to keep Solr in sync.
	 *
	 * @return True if context is deleted or under deletion, false if not.
	 */
	public boolean isDeleted();

}