001: /*
002: * Copyright 2004 Outerthought bvba and Schaubroeck nv
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.outerj.daisy.repository.namespace;
017:
018: import org.outerj.daisy.repository.RepositoryException;
019:
020: /**
021: * Manages the namespaces the repository knows about.
022: *
023: * <p>The NamespaceManager can be retrieved via {@link org.outerj.daisy.repository.Repository#getNamespaceManager()}.
024: *
025: * <p>The purpose of namespaces is to be able to avoid name collisions
026: * (or in case of documents, ID-collisions) between repository servers
027: * when exchanging entities (e.g. through export/import) between them.
028: *
029: * <p>At the time of this writing, namespaces are only used for documents.
030: *
031: * <p>As long as each repository between which items are exchanged has
032: * its own namespace, collisions will be avoided. So it comes down
033: * to properly managing the namespaces. Making the namespace more unique
034: * (e.g. long random string) will of course lower the possibility
035: * that two repositories use the same namespace. However, such namespaces
036: * are not so friendly to work with.
037: *
038: * <p>A namespace has a fingerprint which is used as additional verification
039: * that two namespaces are really the same. This is useful since the
040: * namespace name will often be a short string (e.g. XYZ), so there is a
041: * realistic chance that another repository uses the same namespace name.
042: * The fingerprint then allows to verify the namespaces really correspond.
043: *
044: * <p>Note that in contrast with other entities in Daisy, which are
045: * primarily identified by ID and can be renamed (e.g. document types, users),
046: * a namespace cannot be renamed. This is because the namespace name
047: * serves as the primary identification. [The current implementation also
048: * relies on this, i.e. it assumes the mapping internal ID - namespace name
049: * never changes.]
050: *
051: * @since Daisy 2.0
052: */
053: public interface NamespaceManager {
054: /**
055: * Returns the namespace for the current repository. All entities
056: * (documents) created in this repository are by default created in
057: * this namespace. This method returns exactly the same as
058: * {@link org.outerj.daisy.repository.Repository#getNamespace()}.
059: */
060: String getRepositoryNamespace();
061:
062: /**
063: * @throws NamespaceNotFoundException if the namespace does not exist.
064: */
065: Namespace getNamespace(String name)
066: throws NamespaceNotFoundException;
067:
068: /**
069: * Gets a namespace by internal namespace ID. Usually you should not pay
070: * any value to the internal ID and get the namespace by name instead.
071: *
072: * @throws NamespaceNotFoundException if the namespace does not exist.
073: */
074: Namespace getNamespace(long id) throws NamespaceNotFoundException;
075:
076: /**
077: * @param namespaceName the name should be unique, and conform to the regexp <tt>[a-zA-Z0-9_]+</tt>.
078: * Namespace names are case-sensitive, though two namespaces that are equal-ignoring-case are not allowed.
079: */
080: Namespace registerNamespace(String namespaceName)
081: throws RepositoryException;
082:
083: Namespace registerNamespace(String namespaceName, String fingerprint)
084: throws RepositoryException;
085:
086: /**
087: * Unregisters (deletes) a namespace.
088: *
089: * <p>Unregistering a namespace is only possible if it is not in use anymore.
090: */
091: Namespace unregisterNamespace(String namespaceName)
092: throws RepositoryException;
093:
094: /**
095: * Unregisters (deletes) a namespace.
096: *
097: * <p>Unregistering a namespace is only possible if it is not in use anymore.
098: */
099: Namespace unregisterNamespace(long id) throws RepositoryException;
100:
101: Namespaces getAllNamespaces() throws RepositoryException;
102: }
|