src/main/java/org/odftoolkit/odfdom/taglet/OdfElementTaglet.java

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * Copyright 2009 IBM. All rights reserved.
 * Copyright 2010 Oracle and/or its affiliates. All rights reserved.
 * 
 * Use is subject to license terms.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy
 * of the License at http://www.apache.org/licenses/LICENSE-2.0. You can also
 * obtain a copy of the License at http://odftoolkit.org/docs/license.txt
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * 
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
package org.odftoolkit.odfdom.taglet;

import java.util.Map;
import java.util.logging.Logger;

import com.sun.javadoc.Tag;
import com.sun.tools.doclets.Taglet;


/**
 *	This class implements a custom taglet to the map the ODF element to the
 *  declaration of the ODF element in the OpenDocument specification.
 *
 *  The position of the OpenDocument specification in HTML can be provided using
 *  an environment variable or java system property, while the system property overrides
 *  the environment variable.
 *  In case nothing is been a default path within the JavaDoc doc-files directory is being used.
 *
 *  For example the taglet <code>{@odf.element text:span}</code> would be resolved without variable settings to
 *  <code>JAVA_DOC_BASE/doc-files/OpenDocument-v1.2-cd05-part1.html#element-text_span</code>.
 */
 public class OdfElementTaglet implements Taglet {
 
	 private static final Logger LOG = Logger.getLogger(OdfElementTaglet.class.getName());
	 private static final String NAME = "odf.element";
	 private static final String ODF_SPEC_PATH = "../../../../../../doc-files/OpenDocument-v1.2-cd05-part1.html";
	 private static String mOdfSpecPath = null;
	  
     /* FINDING THE ABSOLUTE PATH TO THE ODF SPEC IN HTML:
      * 1) Try to get the odfSpecPath from the Java System variable (ODF_SPEC_PATH)
      * 2) Try to get the odfSpecPath from the environemnt variable (ODF_SPEC_PATH)
      * 3) If both not worked, use the default path
      **/
     static {
         mOdfSpecPath = System.getProperty("ODF_SPEC_PATH");
         if (mOdfSpecPath == null) {
             mOdfSpecPath = System.getenv("ODF_SPEC_PATH");
             if (mOdfSpecPath == null) {
                 mOdfSpecPath = ODF_SPEC_PATH;
                 LOG.info("OdfSpecPath was set to " + mOdfSpecPath + " by class declaration.");
             } else {
                 LOG.info("OdfSpecPath was set to " + mOdfSpecPath + " by environment property 'ODF_SPEC_PATH'.");
             }
         } else {
             LOG.info("OdfSpecPath was set to " + mOdfSpecPath + " by Java System property 'ODF_SPEC_PATH'.");
         }
     }
	     
		/**
		  * Return the name of this custom tag.
		  */
		public String getName() {
		    return NAME;
		}
	    
	    /**
	     * @return true since this tag can be used in a field
	     *         doc comment
	     */
	    public boolean inField() {
	        return true;
	    }

	    /**
	     * @return true since this tag can be used in a constructor
	     *         doc comment
	     */
	    public boolean inConstructor() {
	        return true;
	    }
	    
	    /**
	     * @return true since this tag can be used in a method
	     *         doc comment
	     */
	    public boolean inMethod() {
	        return true;
	    }
	    
	    /**
	     * @return true since this tag can be used in an overview
	     *         doc comment
	     */
	    public boolean inOverview() {
	        return true;
	    }

	    /**
	     * @return true since this tag can be used in a package
	     *         doc comment
	     */
	    public boolean inPackage() {
	        return true;
	    }

	    /**
	     * @return true since this 
	     */
	    public boolean inType() {
	        return true;
	    }
	    
	    /**
	     * Will return true since this is an inline tag.
	     * @return true since this is an inline tag.
	     */
	    
	    public boolean isInlineTag() {
	        return true;
	    }
	    
	    /**
	     * Register this Taglet.
	     * @param tagletMap  the map to register this tag to.
	     */
	    public static void register(Map<String, Taglet> tagletMap) {
	    	OdfElementTaglet tag = new OdfElementTaglet();
	           Taglet t = tagletMap.get(tag.getName());
	           if (t != null) {
	                tagletMap.remove(tag.getName());
	            }
	            tagletMap.put(tag.getName(), tag);
	    }

	    /**
	     * Given the <code>Tag</code> representation of this custom
	     * tag, return its string representation.
	     * @param tag he <code>Tag</code> representation of this custom tag.
	     */
	    public String toString(Tag tag) {
		    int pos = tag.text().lastIndexOf(":");
		    String fragmentIdentifier = "element-" + tag.text().substring(0, pos) + "_" + tag.text().substring(pos + 1);
		    return "<a href=\"" + mOdfSpecPath + "#" + fragmentIdentifier + "\">" + tag.text() + "</a>";
	    }
	    
	    /**
	     * This method should not be called since arrays of inline tags do not
	     * exist.  Method  should be used to convert this
	     * inline tag to a string.
	     * @param tags the array of <code>Tag</code>s representing of this custom tag.
	     */
	    public String toString(Tag[] tags) {
	        return null;
	    }

}