/*
 * @(#)SerialFieldSubWriter.java	1.8 98/04/30
 *
 * Copyright 1993-1997 Sun Microsystems, Inc. 901 San Antonio Road,
 * Palo Alto, California, 94303, U.S.A.  All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * CopyrightVersion 1.2
 *
 */

package com.sun.tools.doclets.standard;

import com.sun.javadoc.*;
import com.sun.tools.doclets.*;
import java.util.Arrays;

/**
 * Generate serialized form for serializable fields. 
 * Documentation denoted by the tags <code>serial</code> and 
 * <code>serialField<\code> is processed.
 *
 * @author Joe Fialli
 */
public class SerialFieldSubWriter extends FieldSubWriter {
    SerialFieldSubWriter(SubWriterHolderWriter writer) {
        super(writer);
    }

    public ProgramElementDoc[] members(ClassDoc cd) {
        FieldDoc[] array = cd.serializableFields();
	Arrays.sort(array);
	return array;
    }

    void printSignature(MemberDoc member) {
        FieldDoc field = (FieldDoc)member;
        printHead(member);
	writer.pre();
        printTypeLink(field.type());
        print(' ');
        bold(field.name());
	writer.preEnd();
    }

    protected void printHeader(ClassDoc cd) {
        writer.anchor("serializedForm");
        writer.printTableHeadingBackground(writer.getText("doclet.Serialized_Form_fields"));
    }

    protected void printFooter(ClassDoc cd) {
        //writer.hr();
    }

    /**
     * Print a default Serializable field or
     * print all Serializable fields documented by 
     * <code>serialField</code> tags.
     */
    protected void printMember(ProgramElementDoc member) {
        FieldDoc field = (FieldDoc)member;
	ClassDoc cd = field.containingClass();
	if (cd.definesSerializableFields()) {

	    // Process Serializable Fields specified as array of ObjectStreamFields.

	    //if serialPersistentField array has a javadoc comment, print it.
	    boolean printedHeader = false;
	    String comment =  field.commentText();
	    if (comment.length() > 0) {
		writer.printMemberHeader();
		printedHeader = true;
		printFullComment(field);
                writer.printMemberFooter();
	    }

	    //Print a member for each serialField tag.
	    //(There should be one serialField tag per ObjectStreamField element.)
	    SerialFieldTag[] tags = field.serialFieldTags();
	    Arrays.sort(tags);
	    for (int i = 0; i < tags.length; i++) {
		if (! printedHeader) {
		    writer.printMemberHeader();
		    printedHeader = true;
		}
		printSignature(tags[i]);
		printComment(tags[i]);
                writer.printMemberFooter();
	    }
	} else { 

	    // Process default Serializable field.
	    if ((field.tags("serial").length == 0) && ! field.isSynthetic()) {
	       Standard.configuration().
		   standardmessage.warning("doclet.MissingSerialTag", 
			      cd.qualifiedName(), field.name());
	    }
	    printSignature(field);
	    printFullComment(field);
	}
    }

    /*
     * Print comment for a default Serializable field.
     *
     * If serial tag has an optional comment, allow that
     * comment to supercede the javadoc comment for the field.
     */
    protected void printComment(ProgramElementDoc member) {
	String comment = null;

	Tag[] tags = member.tags("serial");
	if (tags.length > 0 && tags[0].text().length() > 0) {
	    comment = tags[0].text();
	} else
	    comment = member.commentText();
        if (comment.length() > 0) {
            writer.dd();
            print(comment);
            // writer.p();
        }
    }

    protected void printTags(ProgramElementDoc member) {
	super.printTags(member);
	printSinceTag(member);
    }

    /* This method is just like tools.doclets.HtmlDocWriter.printSeeTag()
     * for Since tag. So it might belong in that class.
     */
    private void printSinceTag(ProgramElementDoc member) {
        Tag[] sinces = member.tags("since");
        if (sinces.length > 0 ) {
            writer.dl();
            if (sinces.length > 0) {
                // There is going to be only one Since tag.
                writer.dt();
                writer.boldText("doclet.Since");
                writer.print(' ');
                writer.dd();
                writer.println(sinces[0].text());
                writer.ddEnd();
            }
	    writer.dlEnd();
	}
    }

    /* Methods for processing serialField fieldName fieldType description.*/
    void printSignature(SerialFieldTag sftag) {
	writer.pre();
	ClassDoc fieldTypeDoc = sftag.fieldTypeDoc();
	if (fieldTypeDoc != null) {
	    writer.printClassLink(fieldTypeDoc);
        } else {
	    writer.print(sftag.fieldType());
	}
        print(' ');
        bold(sftag.fieldName());
	writer.preEnd();
    }

    private void printComment(SerialFieldTag sftag) {
	writer.dl();
        writer.dd();
        writer.print(sftag.description());
	writer.dlEnd();
    }

    /* The methods following this comment have no meaning for SerialFields.*/
    protected void printDeprecatedLink(ProgramElementDoc member) {
    }

    public void printSummaryLabel(ClassDoc cd) {
    }

    public void printInheritedSummaryLabel(ClassDoc cd) {
    }

    protected void printSummaryLink(ClassDoc cd, ProgramElementDoc member) {
    }

    protected void printInheritedSummaryLink(ClassDoc cd, 
                                             ProgramElementDoc member) {
    }

    protected void printSummaryType(ProgramElementDoc member) {
    }
}