content: /**
   *  Copyright (c) 2013-2016 Angelo ZERR and Genuitec LLC.
   *  All rights reserved. This program and the accompanying materials
   *  are made available under the terms of the Eclipse Public License v1.0
   *  which accompanies this distribution, and is available at
   *  http://www.eclipse.org/legal/epl-v10.html
   *
   *  Contributors:
   *  Piotr Tomiak <piotr@genuitec.com> - initial API and implementation
   *  Angelo Zerr <angelo.zerr@gmail.com> - initial API and implementation
   */
  package tern;
  
  import java.io.IOException;
  
  import tern.server.protocol.TernFile;
  import tern.server.protocol.html.ScriptTagRegion;
  
  public interface ITernFile extends ITernAdaptable {
  	
  	/**
  	 * Protocol for file hosted in a different Tern project within the workspace
  	 */
  	String PROJECT_PROTOCOL = "project://"; //$NON-NLS-1$
  	
  	/**
  	 * Protocol for file from outside the workspace, referred by its filesystem path
  	 */
  	String EXTERNAL_PROTOCOL = "external://"; //$NON-NLS-1$
  	
  	/**
  	 * Returns name of the file as passed to the tern server. It can be e.g.:
  	 * <ul>
  	 * <li>{@code src/bar.js}: when file belongs to the same project</li> 
  	 * <li>{@code project://JSProject/foo.js}: when file belongs to a different project in the workspace</li>
  	 * <li>{@code external://C:\JS resources\jquery.js}: when file does not belong to the workspace</li>
  	 * </ul>
  	 * Name is created in context of the project.
  	 * 
  	 * @return full file name
  	 */
  	String getFullName(ITernProject context);
  
  	/**
  	 * Returns the last segment of the full file name. E.g. {@bar.js};
  	 * 
  	 * @return last segment of the file name
  	 */
  	String getFileName();
  	
  	/**
  	 * Returns whether the file is present in the filesystem and
  	 * is accessible. This should be a relatively fast method and in 
  	 * case of non filesystem files, it may return false if method is sure that 
  	 * contents are not accessible. Even if this method returns true,
  	 * getContents method can still fail with IOException.
  	 */
  	boolean isAccessible();
  	
  	/**
  	 * Returns contents of the file.
  	 * 
  	 * @return contents of the file, never null
  	 * @throws IOException if contents of the file cannot be retrieved
  	 */
  	String getContents() throws IOException;
  	
  	/**
  	 * Returns file relative to the given one, or null if there is no such file. 
  	 * 
  	 * @param relativePath Relative path to the requested file.
  	 * @return Relative file or null
  	 */
  	ITernFile getRelativeFile(String relativePath);
  	
  	/**
  	 * Provides a way to adapt ITernFile to an environment specific object representing file.
  	 * E.g. it can return {@link java.io.File} object or Eclipse 
  	 * {@code org.eclipse.core.resources.IFile}. 
  	 * 
  	 * @param adapterClass
  	 * @return Adapter extending/implementing requested class or null
  	 */
  	Object getAdapter(@SuppressWarnings("rawtypes") Class adapterClass);
  
  	/**
  	 * Convenience method to provide extension of referred file.
  	 * @return
  	 */
  	String getFileExtension();
  	
  	/**
  	 * Converts file to tern server file,
  	 * which can be sent over to the server
  	 * 
  	 * @return
  	 * @throws IOException 
  	 */
  	TernFile toTernServerFile(ITernProject context) throws IOException;
  	
  	/**
  	 * Returns an array of tag names, which contents should be treated as 
  	 * JavaScript content. 
  	 * @return
  	 */
  	ScriptTagRegion[] getScriptTags(ITernProject context);
  	
  }
  