001/**
002 *  '$RCSfile$'
003 *  '$Author: barseghian $'
004 *  '$Date: 2010-06-24 00:25:10 +0000 (Thu, 24 Jun 2010) $'
005 *  '$Revision: 24970 $'
006 *
007 *  For Details:
008 *  http://www.kepler-project.org
009 *
010 *  Copyright (c) 2010 The Regents of the
011 *  University of California. All rights reserved. Permission is hereby granted,
012 *  without written agreement and without license or royalty fees, to use, copy,
013 *  modify, and distribute this software and its documentation for any purpose,
014 *  provided that the above copyright notice and the following two paragraphs
015 *  appear in all copies of this software. IN NO EVENT SHALL THE UNIVERSITY OF
016 *  CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
017 *  OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
018 *  DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE
019 *  POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY
020 *  DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
021 *  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
022 *  SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
023 *  CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
024 *  ENHANCEMENTS, OR MODIFICATIONS.
025 */
026
027package org.kepler.kar;
028
029import java.io.InputStream;
030import java.util.Hashtable;
031import java.util.Vector;
032
033import org.kepler.objectmanager.cache.CacheObject;
034import org.kepler.objectmanager.lsid.KeplerLSID;
035
036import ptolemy.actor.gui.TableauFrame;
037
038public interface KAREntryHandler {
039
040        /**
041         * The getTypeName() method must return the type of object that this
042         * KAREntryHandler saves.  This method should return the KAR version 1.0
043         * type name or null if version 1.0 is not supported by this handler.
044         * 
045         *       */
046        public String getTypeName();
047        
048        /**
049         * This method should return true if this KAREntryHandler can handle the
050         * specified type.  The type passed in is the binary class name of the file.
051         * 
052         * @param typeName
053         *       */
054        public boolean handlesType(String typeName);
055        
056        /**
057         * The initialize method is called directly after instantiating this
058         * KAREntryHandler.
059         */
060        public void initialize();
061        
062        /**
063         * This method should return a CacheObject that will be put into the cache.
064         * Once all the contents of the KAR exist in the cache then the open method
065         * is called.  In this way each entry in the kar can have access to all the
066         * other entries through the cache when they get opened.
067         * 
068         * @param karFile
069         * @param entry
070         * @return the CacheObject that will be put into the CacheManager
071         * @throws Exception
072         */
073        public CacheObject cache(KARFile karFile, KAREntry entry) throws Exception;
074
075        /**
076         * When a KAR file is opened, any entries in the KAR file that have the same
077         * type as this KAREntryHandler will be passed to this open method.  This
078         * method will always be called after the cache method.
079         * 
080         * @param karFile
081         * @param entry
082         * @param tableauFrame
083         * @return boolean true if the entry was opened successfully.
084         * @throws Exception
085         */
086        public boolean open(KARFile karFile, KAREntry entry, TableauFrame tableauFrame) throws Exception;
087
088        /**
089         * Return an array of KAREntry objects that are to be saved for the given
090         * lsids. 
091         * 
092         * @param lsid
093         * @param karLsid the lsid of the containing KAR
094         * @param tableauFrame
095         * @return an array of KAREntries to be saved with this LSID object.
096         * @throws Exception
097         */
098        public Hashtable<KAREntry,InputStream> save(Vector<KeplerLSID> lsids, KeplerLSID karLsid, 
099                        TableauFrame tableauFrame) throws Exception;
100}