NodeLibrary.java :  » Source-Control » sourcejammer » org » sourcejammer » project » model » Java Open Source

/*
 *  Copyright (C) 2001, 2002 Robert MacGrogan
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 *
 * $Archive: SourceJammer$
 * $FileName: NodeLibrary.java$
 * $FileID: 4435$
 *
 * Last change:
 * $AuthorName: Rob MacGrogan$
 * $Date: 7/23/03 12:09 PM$
 * $Comment: Get rid of read-only getFileNode().$
 */

package org.sourcejammer.project.model;

import org.sourcejammer.server.security.ObjectLockingException;
import org.sourcejammer.server.security.SecurityException;
import org.sourcejammer.project.controller.*;
import org.sourcejammer.project.NodeList;
import org.sourcejammer.server.source.Delta;
import org.sourcejammer.project.view.NodeInfo;
import org.sourcejammer.server.source.TextLineReader;
import org.sourcejammer.util.SourceJammerVersionException;
import org.sourcejammer.server.source.TextDiff;
import org.sourcejammer.project.NodeDoesNotExistException;

/**
 * Title: $FileName: NodeLibrary.java$
 * @author $AuthorName: Rob MacGrogan$
 * @version $VerNum: 9$
 * $KeyWordsOff: $<br><br>
 * 
 * Interface for a factory class that retrieves or constructs nodes based on
 * unique ID. A Project/File node cache could be added to the classes
 * implementing this interface
 */
public interface NodeLibrary {

  /**
   * Retrieve or construct a ProjectNode based on it's node id.
   */
  public ProjectNode getProjectNode(long nodeID)
          throws FileAccessException, ProjectDoesNotExistException, SecurityException;


  public MasterFileNode getMasterFileNode(long nodeID)
          throws FileAccessException, FileDoesNotExistException, SecurityException;

  /**
   * Retrieve or construct a FileNode based on it's node id.
   */
  public FileNode getFileNode(long nodeID)
          throws FileAccessException, FileDoesNotExistException, SecurityException;

  /**
   * Releases the node after use.
   */
  public void releaseNode(ControllerNode nd)
          throws FileAccessException;


  /**
   * Subclasses should implement to store version file in the model implementation.
   * FileNode must be locked and passed key must "fit" the FileNode, or
   * ControllerNodeLockException is thrown.
   */
  public void storeVersionFull(FileNode ndFile, long fileKey, NodeInfo versionNode, java.io.File file)
          throws FileAccessException;

  /**
   * Subclasses should implement to store file delta in the model implementation.
   * FileNode must be locked and passed key must "fit" the FileNode, or
   * ControllerNodeLockException is thrown.
   */
  public void storeVersionDelta(FileNode ndFile, long fileKey, NodeInfo versionNode, java.io.File file)
          throws FileAccessException;


  public void storeVersionTextDiff(FileNode ndFile, long fileKey, NodeInfo versionNode, TextDiff file)
        throws FileAccessException;


  /**
   * Subclasses should implement this to return a new ProjectNode
   * object. Unique ID for new project will be already be set in returned Node.
   */
  public ProjectNode getNewProjectFromModel() throws FileAccessException;

  /**
   * Subclasses should implement this to return a new FileNode
   * object. Unique Id for file will already be set in returned Node.
   */
  public FileNode getNewFileNodeFromModel() throws FileAccessException;

  /**
   * Returns next unique ID for a version.
   */
  public long getNextVersionNodeID() throws FileAccessException;

  public void storeVersionComment(FileNode ndFile, long fileKey, long versionID, String comment)
          throws FileAccessException, SecurityException;

  public String retrieveVersionComment(long versionID)
          throws FileAccessException;

  public byte[] retrieveVersionFull(NodeInfo versionNode)
          throws FileAccessException, WrongFileTypeException;

  public java.io.File getSourceFilePointer(NodeInfo versionNode);

  public java.io.File getVersionCommentPointer(NodeInfo versionNode);

  /**
   * When implemented, this method returns the full source of the specified
   * VersionNode as a TextLineReader. This method should only be called for
   * files stored as Text. Implementing classes should throw WrongFileType if
   * the underlying file is not text.
   */
  public TextLineReader retrieveVersionTextLineReader(NodeInfo versionNode)
          throws FileAccessException, WrongFileTypeException, SourceJammerVersionException;

  public Delta retrieveVersionDelta(NodeInfo versionNode)
          throws FileAccessException, WrongFileTypeException;

  public Delta retrieveVersionTextDelta(NodeInfo versionNode)
          throws FileAccessException, WrongFileTypeException;

  public java.io.File retrieveVersionDeltaFile(NodeInfo versionNode)
          throws FileAccessException, WrongFileTypeException;

  public long lockNode(MasterFileNode nd) throws SecurityException;


  /**
   * Locks the node and returns the key. Times out after default
   * number of milliseconds.
   */
  public long lockNode(ControllerNode nd) throws SecurityException;


  /**
   * Only deleted the project file. It is up to the calling routine to delete
   * any file object, as needed.
   */
  public void permanentlyDeleteProject(long projectID)
          throws SecurityException, ProjectDoesNotExistException, FileAccessException;

  /**
   * Permanently remove all vestiges of specified file from model. This
   * method does the following:<br><br>
   * 
   * <li>Removes file from all parents</li>
   * <li>Removes file from removed listing in all parents from which it has already been removed</li>
   * <li>Deletes all source and comments</li>
   * <li>Deletes file itself</li>
   * <li>Removes File object from cache.</li>
   */
  public void permanentlyDeleteFile(long fileID) 
          throws SecurityException, FileDoesNotExistException, 
                 FileAccessException;


  /**
   * Low impact way of getting a node's name without adding the node or any of it's
   * children to the cache.
   */
  public String getProjectChildName(ProjectChild child)
        throws FileAccessException, NodeDoesNotExistException;

  /**
   * Remove all files assocaited with version from model.
   */
  public void removeVersion(FileNode ndFile, long fileKey, long versionID)
        throws FileAccessException, NoSuchVersionException;


  /**
   * Returns a new MasterFile object with unique id already set.
   */
  public MasterFileNode getNewMasterFileFromModel() throws FileAccessException;

}