/* 
    P/P   *  Method: org.apache.roller.weblogger.business.FileManager__static_init
          */
     1  /*
     2   * Licensed to the Apache Software Foundation (ASF) under one or more
     3   *  contributor license agreements.  The ASF licenses this file to You
     4   * under the Apache License, Version 2.0 (the "License"); you may not
     5   * use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *     http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.  For additional information regarding
    15   * copyright in this work, please see the NOTICE file in the top level
    16   * directory of this distribution.
    17   */
    18  
    19  package org.apache.roller.weblogger.business;
    20  
    21  import java.io.InputStream;
    22  import org.apache.roller.weblogger.pojos.ThemeResource;
    23  import org.apache.roller.weblogger.pojos.Weblog;
    24  
    25  
    26  /**
    27   * Interface for managing files uploaded to Roller.
    28   */
    29  public interface FileManager {
    30      
    31      /**
    32       * Get a reference to a specific file in a weblog's uploads area.
    33       * 
    34       * This method always returns a valid file or will throw an exception
    35       * if the specificed path doesn't exist, is a directory, or can't be read.
    36       * 
    37       * @param weblog The weblog we are working on.
    38       * @param path The relative path to the desired resource within 
    39       * the weblog's uploads area.
    40       *
    41       * @throws FileNotFoundException If path does not exist.
    42       * @throws FilePathException If path is invalid, is a directory, or can't be read.
    43       *
    44       * @return ThemeResource representing the real file resource.
    45       */
    46      public ThemeResource getFile(Weblog weblog, String path) 
    47          throws FileNotFoundException, FilePathException;
    48      
    49      
    50      /**
    51       * Get list of files from a specific path of the weblog's uploads area.
    52       * 
    53       * This method will return a ThemeResource[] array of all files at the 
    54       * given path if it exists, otherwise it will throw an exception.
    55       * 
    56       * This method should return the files at the root of the weblog's uploads
    57       * area given a path value of null, "" (empty string), or "/"
    58       * 
    59       * This method should NOT return any resources which represent directories.
    60       *
    61       * @param weblog The weblog we are working on.
    62       * @param path The relative path to the desired resource within 
    63       * the weblog's uploads area.
    64       * 
    65       * @throws FileNotFoundException If path does not exist.
    66       * @throws FilePathException If path is invalid, is not a directory, or can't be read.
    67       *
    68       * @return ThemeResource[] of files in website's uploads area at given path.
    69       */
    70      public ThemeResource[] getFiles(Weblog weblog, String path) 
    71          throws FileNotFoundException, FilePathException;
    72      
    73      
    74      /**
    75       * Get list of directories from a weblog's uploads area.
    76       * 
    77       * This method will return an array of all dirs in the weblogs' uploads 
    78       * area, otherwise it will throw an exception.
    79       * 
    80       * @param weblog The weblog we are working on.
    81       * 
    82       * @throws FileNotFoundException If path does not exist.
    83       * @throws FilePathException If path is invalid, or can't be read.
    84       *
    85       * @return ThemeResource[] of directories in website's uploads area.
    86       */
    87      public ThemeResource[] getDirectories(Weblog weblog)
    88              throws FileNotFoundException, FilePathException;
    89      
    90      
    91      /**
    92       * Save a file to weblog's uploads area, with can-save check.
    93       * 
    94       * @param weblog The weblog we are working on.
    95       * @param path The relative path to the desired location within 
    96       * the weblog's uploads area where the file should be saved.
    97       * @param contentType Content type of the file.
    98       * @param size Size of file to be saved.
    99       * @param is InputStream to read the file from.
   100       *
   101       * @throws FileNotFoundException If path to save location does not exist.
   102       * @throws FilePathException If path is invalid, is not a directory, or can't be read.
   103       * @throws FileIOException If there is an unexpected error during the save.
   104       */
   105      public void saveFile(Weblog weblog, 
   106                           String path, 
   107                           String contentType, 
   108                           long size,
   109                           InputStream is)
   110          throws FileNotFoundException, FilePathException, FileIOException;
   111      
   112      
   113      /**
   114       * Save a file to weblog's uploads area, with optional can-save check.
   115       * 
   116       * @param weblog The weblog we are working on.
   117       * @param path The relative path to the desired location within 
   118       * the weblog's uploads area where the file should be saved.
   119       * @param contentType Content type of the file.
   120       * @param size Size of file to be saved.
   121       * @param is InputStream to read the file from.
   122       *
   123       * @throws FileNotFoundException If path to save location does not exist.
   124       * @throws FilePathException If path is invalid, is not a directory, or can't be read.
   125       * @throws FileIOException If there is an unexpected error during the save.
   126       */
   127      public void saveFile(Weblog weblog, 
   128                           String path, 
   129                           String contentType, 
   130                           long size,
   131                           InputStream is,
   132                           boolean checkCanSave)
   133          throws FileNotFoundException, FilePathException, FileIOException;
   134      
   135      
   136      /**
   137       * Create an empty subdirectory in the weblog's uploads area.
   138       *
   139       * @param weblog The weblog we are working on.
   140       * @param path The relative path to the desired location within 
   141       * the weblog's uploads area where the directory should be created.
   142       *
   143       * @throws FileNotFoundException If path to create location does not exist.
   144       * @throws FilePathException If path is invalid, is not a directory, or can't be read.
   145       * @throws FileIOException If there is an unexpected error during the create.
   146       */
   147      public void createDirectory(Weblog weblog, String path) 
   148          throws FileNotFoundException, FilePathException, FileIOException;
   149      
   150      
   151      /**
   152       * Delete file or directory from weblog's uploads area.
   153       * 
   154       * @param weblog The weblog we are working on.
   155       * @param path The relative path to the file within the weblog's uploads 
   156       * area that should be deleted.
   157       *
   158       * @throws FileNotFoundException If path does not exist.
   159       * @throws FilePathException If path is invalid, or can't be read.
   160       * @throws FileIOException If there is an unexpected error during the delete.
   161       */
   162      public void deleteFile(Weblog weblog, String path) 
   163          throws FileNotFoundException, FilePathException, FileIOException;
   164      
   165      
   166      /**
   167       * Delete all files associated with a given weblog, including the root folder.
   168       *
   169       * The only real use of this method is for when a weblog is being deleted.
   170       *
   171       * @param weblog The weblog to delete all files from.
   172       * @throws FileIOException If there is an unexpected error during the delete.
   173       */
   174      public void deleteAllFiles(Weblog weblog)
   175          throws FileIOException;
   176      
   177      
   178      /** 
   179       * Is the given weblog over the file-upload quota limit?
   180       *
   181       * @param weblog The weblog we are working on.
   182       *
   183       * @return True if weblog is over set quota, False otherwise.
   184       */
   185      public boolean overQuota(Weblog weblog);
   186      
   187      
   188      /**
   189       * Release all resources associated with Roller session.
   190       */
   191      public void release();
   192      
   193  }