/*
 * Common Library for TBAS Softwares
 * Language: Java
 *
 * All Rights Reserved.
 * (c) Copyright 2003 by Tsukuba Bunko.
 *
 * $Id: ResourceLocator.java,v 1.1 2003/08/31 08:20:49 ppoi Exp $
 */
package tsukuba_bunko.util;

import	java.io.File;


/**
 * リソースのファイルシステム上での位置(ファイルパス)を取得する機能を提供します。
 * @author	$Author: ppoi $
 * @version	$Revision: 1.1 $
 */
public abstract class ResourceLocator	{

	/**
	 * インスタンス化する <code>ResourceLocator</code> 実装クラスを指定するシステムプロパティ："tsukuba_bunko.util.ResourceLocator.impl"
	 */
	public static final String	IMPL_CLASS_PROPERTY = "tsukuba_bunko.util.ResourceLocator.impl";


	/**
	 * <code>ResourceLocator</code> のインスタンスを生成します。
	 */
	protected ResourceLocator()
	{
		super();
	}


	/**
	 * <code>resourceName</code> で指定されるリソースを現在のスレッドのコンテクストで検索し、そのファイルシステム上での位置を取得します。
	 * @param	resourceName	ファイルパスを取得するリソースのリソース名
	 * @return	リソースのファイルパス。検出不能な場合 <code>null</code>
	 * @throws	ResourceDetectionException	リソースの検出に失敗した場合
	 */
	public File findLocation( String resourceName )
		throws ResourceDetectionException
	{
		return findLocation( resourceName, Thread.currentThread().getContextClassLoader() );
	}

	/**
	 * <code>resourceName</code> で指定されるリソースを指定されたクラスローダで検索し、そのファイルシステム上での位置を取得します。
	 * @param	resourceName	ファイルパスを取得するリソースのリソース名
	 * @param	classLoader	リソースを検索するクラスローダ
	 * @return	リソースのファイルパス
	 * @throws	ResourceDetectionException	リソースの検出に失敗した場合
	 */
	public abstract File findLocation( String resourceName, ClassLoader classLoader )
		throws ResourceDetectionException;


//
//	ファクトリ
//
	/**
	 * <code>ResourceLocator</code> インスタンスを生成します。
	 * 生成される <code>ResourceLocator</code> インスタンスのクラスはシステムプロパティを元に決定されます。プロパティ名は {@link #IMPL_CLASS_PROPERTY} を参照してください。
	 * システムプロパティが設定されていない場合、デフォルトの <code>ResourceLocator</code> 実装クラスが使用されます。
	 * @return	生成された <code>ResourceLocator</code> インスタンス
	 * @throws	ClassNotFoundException	指定されたクラスが現在のスレッドのコンテクストで見つからなかった場合
	 * @throws	InstantiationException	実装クラスのインスタンス化に失敗した場合
	 * @throws	IllegalAccessException	実装クラス、またはそのコンストラクタのアクセス権が public でない場合
	 */
	public static ResourceLocator newInstance()
		throws ClassNotFoundException, InstantiationException, IllegalAccessException
	{
		String	className = System.getProperty( ResourceLocator.IMPL_CLASS_PROPERTY, "tsukuba_bunko.util.locator.ResourceLocatorImpl" );
		return newInstance( Thread.currentThread().getContextClassLoader().loadClass(className) );
	}

	/**
	 * <code>ResourceLocator</code> インスタンスを生成します。
	 * @param	implClass	<code>ResourceLocator</code> 実装クラス
	 * @return	生成された <code>ResourceLocator</code> インスタンス
	 * @throws	InstantiationException	実装クラスのインスタンス化に失敗した場合
	 * @throws	IllegalAccessException	実装クラス、またはそのコンストラクタのアクセス権が public でない場合
	 */
	public static ResourceLocator newInstance( Class implClass )
		throws InstantiationException, IllegalAccessException
	{
		if( implClass == null )	{
			throw new IllegalArgumentException( "implement class is not specified." );
		}
		else if( !ResourceLocator.class.isAssignableFrom(implClass) )	{
			throw new IllegalArgumentException( implClass.getName() + " is not extends from ResourceLocator." );
		}

		return (ResourceLocator)implClass.newInstance();
	}
}