001 // SECTION-START[License Header]
002 // <editor-fold defaultstate="collapsed" desc=" Generated License ">
003 /*
004 * Copyright (c) 2010 The JOMC Project
005 * Copyright (c) 2005 Christian Schulte <schulte2005@users.sourceforge.net>
006 * All rights reserved.
007 *
008 * Redistribution and use in source and binary forms, with or without
009 * modification, are permitted provided that the following conditions
010 * are met:
011 *
012 * o Redistributions of source code must retain the above copyright
013 * notice, this list of conditions and the following disclaimer.
014 *
015 * o Redistributions in binary form must reproduce the above copyright
016 * notice, this list of conditions and the following disclaimer in
017 * the documentation and/or other materials provided with the
018 * distribution.
019 *
020 * THIS SOFTWARE IS PROVIDED BY THE JOMC PROJECT AND CONTRIBUTORS "AS IS"
021 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
022 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
023 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE JOMC PROJECT OR
024 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
025 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
026 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
027 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
028 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
029 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
030 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
031 *
032 * $Id: SequenceDirectory.java 2244 2010-06-29 07:58:09Z schulte2005 $
033 *
034 */
035 // </editor-fold>
036 // SECTION-END
037 package org.jomc.sequences;
038
039 import java.math.BigInteger;
040 import java.util.Set;
041
042 // SECTION-START[Documentation]
043 // <editor-fold defaultstate="collapsed" desc=" Generated Documentation ">
044 /**
045 * Directory of sequences.
046 *
047 * <p>
048 * This specification declares a multiplicity of {@code One}.
049 * An application assembler may provide either no or one implementation of this specification.
050 * </p>
051 *
052 * <p>
053 * Use of class {@link org.jomc.ObjectManager ObjectManager} is supported for accessing implementations.
054 * <pre>
055 * SequenceDirectory object = ObjectManagerFactory.getObjectManager( getClass().getClassLoader() ).getObject( SequenceDirectory.class );
056 * SequenceDirectory object = ObjectManagerFactory.getObjectManager( getClass().getClassLoader() ).getObject( SequenceDirectory.class, "<i>implementation name</i>" );
057 * </pre>
058 * </p>
059 *
060 * <p>
061 * This specification applies to {@code Singleton} scope.
062 * The same singleton object is returned whenever requested.
063 * </p>
064 *
065 * @author <a href="mailto:schulte2005@users.sourceforge.net">Christian Schulte</a> 1.0
066 * @version $Id: SequenceDirectory.java 2244 2010-06-29 07:58:09Z schulte2005 $
067 */
068 // </editor-fold>
069 // SECTION-END
070 // SECTION-START[Annotations]
071 // <editor-fold defaultstate="collapsed" desc=" Generated Annotations ">
072 @javax.annotation.Generated( value = "org.jomc.tools.SourceFileProcessor 1.0", comments = "See http://jomc.sourceforge.net/jomc/1.0/jomc-tools" )
073 // </editor-fold>
074 // SECTION-END
075 public interface SequenceDirectory
076 {
077 // SECTION-START[SequenceDirectory]
078
079 /**
080 * Gets the total number of sequences stored in the directory.
081 *
082 * @return The total number of sequences stored in the directory.
083 *
084 * @throws SequencesSystemException if getting the total number of sequences fails.
085 */
086 BigInteger getSequenceCount() throws SequencesSystemException;
087
088 /**
089 * Gets the capacity limit of the directory.
090 *
091 * @return The capacity limit of the directory.
092 *
093 * @throws SequencesSystemException if getting the capacity limit fails.
094 */
095 BigInteger getCapacityLimit() throws SequencesSystemException;
096
097 /**
098 * Gets a sequence for a given name.
099 *
100 * @param name The name of the sequence to return.
101 *
102 * @return The sequence with name {@code name} or {@code null} if no sequence matching {@code name} exists in the
103 * directory.
104 *
105 * @throws SequencesSystemException if getting the sequence fails.
106 */
107 Sequence getSequence( String name ) throws SequencesSystemException;
108
109 /**
110 * Adds a sequence to the directory.
111 *
112 * @param sequence The sequence to add to the directory.
113 *
114 * @return The data of the sequence from the directory.
115 *
116 * @throws SequenceVetoException if {@code sequence} holds illegal values.
117 * @throws SequenceExistsException if a sequence with the same name already exists.
118 * @throws CapacityLimitException if the directory's capacity limit has been reached.
119 * @throws SequencesSystemException if adding the sequence fails.
120 */
121 Sequence addSequence( Sequence sequence )
122 throws SequenceVetoException, SequenceExistsException, CapacityLimitException, SequencesSystemException;
123
124 /**
125 * Updates a sequence in the directory.
126 *
127 * @param name The name of the sequence to update.
128 * @param revision The revision of the sequence to update.
129 * @param sequence The data to update the directory with.
130 *
131 * @return The data of the sequence from the directory.
132 *
133 * @throws SequenceVetoException if {@code sequence} holds illegal values.
134 * @throws SequenceNotFoundException if no sequence matching {@code name} exists in the directory.
135 * @throws ConcurrentModificationException if the same sequence got concurrently modified in the directory, that is,
136 * {@code revision} denotes outdated data.
137 * @throws SequencesSystemException if editing the sequence fails.
138 */
139 Sequence editSequence( String name, long revision, Sequence sequence )
140 throws SequenceVetoException, SequenceNotFoundException, ConcurrentModificationException,
141 SequencesSystemException;
142
143 /**
144 * Removes a sequence from the directory.
145 *
146 * @param name The name of the sequence to remove.
147 * @param revision The revision of the sequence to remove.
148 *
149 * @return The data of the removed sequence from the directory.
150 *
151 * @throws SequenceNotFoundException if no sequence matching {@code name} exists in the directory.
152 * @throws ConcurrentModificationException if the same sequence got concurrently modified in the directory, that is,
153 * {@code revision} denotes outdated data.
154 * @throws SequencesSystemException if deleting the sequence fails.
155 */
156 Sequence deleteSequence( String name, long revision )
157 throws SequenceNotFoundException, ConcurrentModificationException, SequencesSystemException;
158
159 /**
160 * Searches the directory for sequences matching the given arguments.
161 *
162 * @param name Text to select sequences whose {@code name} property matches the given text; {@code null} to ignore
163 * property {@code name} in the search.
164 *
165 * @return All sequences matching the given criteria.
166 *
167 * @throws SequencesSystemException if searching the directory fails.
168 */
169 Set<Sequence> searchSequences( String name ) throws SequencesSystemException;
170
171 // SECTION-END
172 }