package org.okip.service.filing.api; /* Copyright (c) 2002 Massachusetts Institute of Technology This work, including any software, documents, or other related items (the "Work"), is being provided by the copyright holder(s) subject to the terms of the MIT OKI(TM) API Definition License. By obtaining, using and/or copying this Work, you agree that you have read, understand, and will comply with the following terms and conditions of the MIT OKI(TM) API Definition License: You may use, copy, and distribute unmodified versions of this Work for any purpose, without fee or royalty, provided that you include the following on ALL copies of the Work that you make or distribute: * The full text of the MIT OKI(TM) API Definition License in a location viewable to users of the redistributed Work. * Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, a short notice similar to the following should be used within the body of any redistributed Work: "Copyright (c) 2002 Massachusetts Institute of Technology. All Rights Reserved." You may modify or create Derivatives of this Work only for your internal purposes. You shall not distribute or transfer any such Derivative of this Work to any location or any other third party. For purposes of this license, "Derivative" shall mean any derivative of the Work as defined in the United States Copyright Act of 1976, such as a translation or modification. THIS WORK PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS IN THE WORK. The name and trademarks of copyright holder(s) and/or MIT may NOT be used in advertising or publicity pertaining to the Work without specific, written prior permission. Title to copyright in the Work and any associated documentation will at all times remain with the copyright holders. */ /* * $Source: /cvs/oki/tech/src/org/okip/service/filing/api/Cabinet.java,v $ */ /** * Cabinets contain other Cabinets and ByteStores, and have * implementation-dependent properties. *

* They may manage quotas, that is, if the implementation supports * quotas, each Agent may be assigned a quota of space used in the * Cabinet. *

* Cabinets contain CabinetEntries, each of which may be a ByteStore or a * Cabinet. They are known by their IDs and name, where * the name is a string which does not include the * implementation-dependant separationCharacter, and may represent a filename. *

* A Cabinet be representable as a jar file and vice * versa. *

* ByteStores and Cabinets are added to Cabinets. Cabinets are created * in CabinetFactories or Cabinets and ByteStores are created in Cabinets. *

* Licensed under the {@link org.okip.service.ApiLicense MIT OKI™ API Definition License}. * * @version $Name: $ / $Revision: 1.10 $ / $Date: 2002/08/23 20:57:33 $ */ public interface Cabinet extends CabinetEntry { /** * Method getProperties * * Return properties of this cabinet. The properties map is * specified using keys of org.okip.service.shared.api.Type, and values of * e.g. Boolean, Long, or Double. The application prepares a map of * desired qualities, e.g.
* key= new Type("Filing", "MIT", "supportsQuota"), * value= new Boolean(true)
* key= new Type("Filing", "MIT", "supportsReplication"), * value= new Boolean(true)
* key= new Type("Filing", "MIT", "minimumReplications"), * value= new Integer(2) * * * @return java.util.Map of properties of this Cabinet and implementation * */ public java.util.Map getProperties() throws FilingException; // not in java.io.File in 1.0-1.4 /** * Create new ByteStore and add it to this Cabinet under the given * name. * * The name must not include this Cabinet's separationCharacter. * * @param name The name to be used * * @return The ByteStore created * * @throws NameCollisionException - if name is already in use by a * CabinetEntry. * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to create a ByteStore. */ public ByteStore createByteStore(String name) throws FilingException; /** * Create new anonymous ByteStore in this cabinet, to be deleted * automatically on exit * * @return The ByteStore created * * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to create a ByteStore. */ public ByteStore createTempByteStore() throws FilingException; /** * Create new Cabinet and add it to this Cabinet under the given * name. * * The name must not include this Cabinet's separationCharacter. * * @param name The name to be used * * @return The Cabinet created * * @throws NameCollisionException - if name is already in use by a * CabinetEntry * @throws IllegalCharacterException - if name includes the * separationCharacter * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to create a Cabinet. */ public Cabinet createCabinet(String name) throws FilingException; /** * Method createByteStore * * * create new anonymous ByteStore in this Cabinet by copying contents and * appropriate attributes of another ByteStore. * * * @param oldByteStore * * @return ByteStore * * @throws NameCollisionException - if name of the oldByteStore is * already in use by a CabinetEntry in this Cabinet * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to create a ByteStore. */ public ByteStore createByteStore(ByteStore oldByteStore) throws FilingException; /** * Create new named ByteStore in this Cabinet by copying contents and * appropriate attributes of another ByteStore. * * @param name * @param oldByteStore * * @return ByteStore * * @throws NameCollisionException - if name is already in use by a * CabinetEntry. * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to create a ByteStore. */ public ByteStore createByteStore(String name, ByteStore oldByteStore) throws FilingException; /** * Add CabinetEntry, must be from same CabinetFactory. * * * @param entry * @param name * * @throws NameCollisionException - if name is already in use by a * CabinetEntry * @throws IllegalCharacterException - if name includes the * separationCharacter. * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to add a Cabinet. * @throws UnsupportedFilingOperationException - if the add/remove semantics * are not supportable in the implmentation. */ public void add(CabinetEntry entry, String name) throws FilingException; /** * Remove CabinetEntry. Does not destroy CabinetEntry. * * * @param entry * * @throws FilingIOException - if an IO error occurs. * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to remove a Cabinet. * @throws UnsupportedFilingOperationException - if the add/remove semantics * are not supportable in the implmentation. */ public void remove(CabinetEntry entry) throws FilingException; /** * Get CabinetEntry from Cabinet by ID. * * @param id * * @return CabinetEntry which has given ID. * * @throws FilingPermissionDeniedException - if Factory Owner * does not have read permission on the CabinetEntry with this ID. * @throws FilingIOException - if an IO error occurs accessing * the CabinetEntry with this ID. * @throws NotFoundException - if there is no CabinetEntry with this * ID in this Cabinet. */ public CabinetEntry getCabinetEntry(ID id) throws FilingException; /** * Get CabinetEntry by name. Not all CabinetEntrys have names, * but if it has a name, it is unique within a Cabinet. * * @param name * * @return CabinetEntry which has given name * * @throws FilingPermissionDeniedException - if Factory Owner * does not have read permission on the CabinetEntry with this name. * @throws FilingIOException - if an IO error occurs accessing * the CabinetEntry with this name. * @throws NotFoundException - if there is no CabinetEntry with this * name in this Cabinet. */ public CabinetEntry getCabinetEntry(String name) throws FilingException; /** * Get an Iterator over all CabinetEntries in this Cabinet. * * @return java.util.Iterator * */ public java.util.Iterator entries() throws FilingException; /** * Return the root Cabinet of this cabinet. * * * @return root Cabinet * * @throws FilingPermissionDeniedException - if Factory Owner * does not have read permission on the root Cabinet. * @throws FilingIOException - if an IO error occurs. */ public Cabinet getRootCabinet() throws FilingException; /** * Return true if this Cabinet is the root Cabinet. * * * @return true if and only if this Cabinet is the root Cabinet. * */ public boolean isRootCabinet() throws FilingException; /** * Set quota for Agent in this Cabinet. * * @param agent * @param quotaBytes * * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to set quotas * @throws FilingIOException - if an IO error occurs. * @throws UnsupportedFilingOperationException - if quotas are not implemented. */ public void setQuota(org.okip.service.shared.api.Agent agent, long quotaBytes) throws FilingException; /** * Get quota for agent in this Cabinet. * * @param agent * * @return long * * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to remove a Cabinet. * @throws UnsupportedFilingOperationException - if quotas are not implemented. */ public long getQuota(org.okip.service.shared.api.Agent agent) throws FilingException; /** * Get quota used by the agent in this Cabinet. * * @param agent * * @return long * * @throws FilingPermissionDeniedException - if Factory Owner * does not have permission to examine the quota of this Agent * @throws FilingIOException - if an IO error occurs. * @throws UnsupportedFilingOperationException - if quotas are not implemented. */ public long getQuotaUsed(org.okip.service.shared.api.Agent agent) throws FilingException; /** * Get space available in Cabinet, for bytes. * * * @return long, space available in Cabinet, in bytes. * * @throws FilingIOException - if an IO error occurs. * @throws UnsupportedFilingOperationException - if space restrictions are * not implemented. */ public long getAvailableBytes() throws FilingException; /** * Get number of bytes used in this Cabinet. * * * @return long - space used in Cabinet, in bytes. * * @throws FilingIOException - if an IO error occurs. * @throws UnsupportedFilingOperationException - if space restrictions are * not implemented. */ public long getUsedBytes() throws FilingException; /** * Compares this this Cabinet to another Cabinet. * * @param cabinet The Cabinet to be compared to this Cabinet * * @return 0 if they are equal, less than 0 or greater than 0 if * they differ, depending on the implementation-dependent quality * used for the comparison. * * @throws FilingPermissionDeniedException - if Factory Owner * does not have read permission on the Cabinet being compared to * @throws FilingIOException - if an IO error occurs reading the * Cabinet being compared to * * @see java.lang.Comparable */ public int compareTo(Cabinet cabinet) throws FilingException; } /* * The following are already in the immutable contract of the hierarchy. * * public boolean equals(Object object) throws FilingException; * public int hashCode()throws FilingException; * public String toString()throws FilingException; * */