001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *   http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.felix.framework.cache;
020    
021    import java.io.File;
022    import java.util.Map;
023    
024    import org.apache.felix.framework.Logger;
025    import org.apache.felix.moduleloader.IContent;
026    
027    /**
028     * <p>
029     * This class implements an abstract revision of a bundle archive. A revision
030     * is an abstraction of a bundle's actual content and is associated with a
031     * parent bundle archive. A bundle archive may have multiple revisions assocaited
032     * with it at one time, since updating a bundle results in a new version of the
033     * bundle's content until the bundle is refreshed. Upon a refresh, then old
034     * revisions are then purged. This abstract class is the base class for all
035     * concrete types of revisions, such as ones for a JAR file or directories. All
036     * revisions are assigned a root directory into which all of their state should
037     * be stored, if necessary. Clean up of this directory is the responsibility
038     * of the parent bundle archive and not of the revision itself.
039     * </p>
040     * @see org.apache.felix.framework.cache.BundleCache
041     * @see org.apache.felix.framework.cache.BundleArchive
042    **/
043    public abstract class BundleRevision
044    {
045        private final Logger m_logger;
046        private final Map m_configMap;
047        private final File m_revisionRootDir;
048        private final String m_location;
049    
050        /**
051         * <p>
052         * This class is abstract and cannot be created. It represents a revision
053         * of a bundle, i.e., its content. A revision is associated with a particular
054         * location string, which is typically in URL format. Subclasses of this
055         * class provide particular functionality, such as a revision in the form
056         * of a JAR file or a directory. Each revision subclass is expected to use
057         * the root directory associated with the abstract revision instance to
058         * store any state; this will ensure that resources used by the revision are
059         * properly freed when the revision is no longer needed.
060         * </p>
061         * @param logger a logger for use by the revision.
062         * @param revisionRootDir the root directory to be used by the revision
063         *        subclass for storing any state.
064         * @param location the location string associated with the revision.
065         * @param trustedCaCerts the trusted CA certificates if any.
066         * @throws Exception if any errors occur.
067        **/
068        public BundleRevision(Logger logger, Map configMap, File revisionRootDir, String location)
069            throws Exception
070        {
071            m_logger = logger;
072            m_configMap = configMap;
073            m_revisionRootDir = revisionRootDir;
074            m_location = location;
075        }
076    
077        /**
078         * <p>
079         * Returns the logger for this revision.
080         * </p>
081         * @return the logger instance for this revision.
082        **/
083        public Logger getLogger()
084        {
085            return m_logger;
086        }
087    
088        /**
089         * <p>
090         * Returns the configuration map for this revision.
091         * </p>
092         * @return the configuration map for this revision.
093        **/
094        public Map getConfig()
095        {
096            return m_configMap;
097        }
098    
099        /**
100         * <p>
101         * Returns the root directory for this revision.
102         * </p>
103         * @return the root directory for this revision.
104        **/
105        public File getRevisionRootDir()
106        {
107            return m_revisionRootDir;
108        }
109    
110        /**
111         * <p>
112         * Returns the location string this revision.
113         * </p>
114         * @return the location string for this revision.
115        **/
116        public String getLocation()
117        {
118            return m_location;
119        }
120    
121        /**
122         * <p>
123         * Returns the main attributes of the JAR file manifest header of the
124         * revision. The returned map is case insensitive.
125         * </p>
126         * @return the case-insensitive JAR file manifest header of the revision.
127         * @throws java.lang.Exception if any error occurs.
128        **/
129        public abstract Map getManifestHeader() throws Exception;
130    
131        public abstract IContent getContent() throws Exception;
132    
133        /**
134         * <p>
135         * This method is called when the revision is no longer needed. The directory
136         * associated with the revision will automatically be removed for each
137         * revision, so this method only needs to be concerned with other issues,
138         * such as open files.
139         * </p>
140         * @throws Exception if any error occurs.
141        **/
142        protected abstract void close() throws Exception;
143    }