ConfigGuideGeneration.java revision a41662c1136b2bb4a4198df89e0e87d2be3ef099
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at legal-notices/CDDLv1_0.txt.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Copyright 2007-2010 Sun Microsystems, Inc.
* Portions Copyright 2011-2015 ForgeRock AS.
*/
/**
* This class allow Configuration Guide documentation generation (html format).
* It is based on the Admin Framework Introspection API
*
*/
public class ConfigGuideGeneration {
// Note : still to be done :
// I18n support. Today all the strings are hardcoded in this file
private static final String ACI_SYNTAX_REL_URL =
"/doc/admin-guide/#about-acis";
private static final String DURATION_SYNTAX_REL_URL =
private final String INHERITANCE_TREE_FILE =
/**
* Entry point for documentation generation.
*
* Properties:
* GenerationDir - The directory where the doc is generated
* LdapMapping - Presence means that the LDAP mapping section is to be
* generated (default is no)
* OpenDJWiki - The URL of the OpenDJ Wiki
* (default is
* OpenDJHome - The URL of the OpenDJ project Home page
* (default is "http://opendj.forgerock.org")
*
* @param args none.
*/
if (generationDir == null) {
// Default dir is prefixed by the system-dependent default temporary dir
}
// Create new dir if necessary
try {
} catch (Exception e) {
e.printStackTrace();
}
ldapMapping = true;
}
if (OpenDJWiki == null) {
// Default is current wiki
}
if (OpenDJHome == null) {
// Default is current OpenDJ project home
}
}
private void generate() {
init();
// Generate the relation tree of all the managed objects
// Generate the inheritance tree of all the managed objects
// Generate all the managed objects and their children
// Generate a list of managed objects
// Generate an index of properties
// Generate the Index page
genIndexPage();
// Generate the Main Top page
// Generate the Welcome page
}
private void init() {
// Build a list of top relations
}
// Enable the client-side class loader to explicitly load classes
// which are not directly reachable from the root configuration
// Bootstrap definition classes.
try {
} catch (InitializationException e) {
e.printStackTrace();
}
// Switch off class name validation in client.
// Switch off attribute type name validation in client.
// Build a sorted list of top managed objects
// root
continue;
}
{
continue;
}
}
// Build a list of top relations by category (core, database, ...)
}
}
}
// Build a list of top managed objects by category (core, database, ...)
}
}
}
}
/**
* Generate the inheritance tree of all the managed objects.
*/
@SuppressWarnings("unchecked")
private void genManagedObjectInheritanceTree(
"Configuration Reference - Inheritance View");
viewHelp("This view represents the inheritance relationships between " +
"configuration components.");
jumpSection();
// Get the list of the category
continue;
}
if (mo.hasChildren()) {
}
}
}
htmlFooter();
}
@SuppressWarnings("unchecked")
private void genMoInheritanceTree(
beginList();
if (mo.hasChildren()) {
}
}
endList();
}
private void jumpSection() {
if (ii != 0) {
}
}
}
/**
* Generate the relation tree of all the managed objects.
*/
private void genManagedObjectRelationTree(
" Configuration Reference - Structure View");
viewHelp("This view represents the structural relationships between " +
"components and indicates how certain components can exist only within " +
"container components.");
jumpSection();
// Get the list of the category
}
htmlFooter();
}
@SuppressWarnings("unchecked")
// Does not generate several entry for the same relation
continue;
}
continue;
}
fromStr = " (from " +
}
if (!inList) {
} else {
}
if (childMo.hasChildren()) {
{
continue;
}
}
}
}
}
beginList();
endList();
}
}
/**
* Generate all the managed objects HTML pages.
*/
@SuppressWarnings("unchecked")
private void genAllManagedObject(
continue;
}
if (mo.hasChildren()) {
}
}
}
//------------------------------------------------------------------------
// Header
//------------------------------------------------------------------------
homeLink();
// title
// Abstract notice
if (mo.hasChildren()) {
"Note: this is an abstract component, that cannot be instantiated.",
}
// description
// sub-components
if (mo.hasChildren()) {
heading3("Direct Subcomponents");
" are available in the server :");
beginList();
@SuppressWarnings("unchecked")
}
endList();
" inherit from the properties described below.");
}
// Parent
heading3("Parent Component");
" component inherits from the " +
}
// Relations
// Page links in case of LDAP mapping
if (ldapMapping) {
newline();
newline();
beginList();
endList();
newline();
}
//------------------------------------------------------------------------
// Properties
//------------------------------------------------------------------------
heading3("Properties");
paragraph("A description of each property follows.");
newline();
// Properties actually defined in this managed object
@SuppressWarnings("unchecked")
} else {
}
}
// basic properties
if (!basicProps.isEmpty()) {
heading4("Basic Properties");
newline();
}
newline();
}
// advanced properties
if (!advancedProps.isEmpty()) {
heading4("Advanced Properties");
newline();
}
newline();
}
if (ldapMapping) {
}
htmlFooter();
}
@SuppressWarnings("unchecked")
return makePropTreeMap(props);
}
private void homeLink() {
.append("margin-bottom:-10px; text-align:right\"><a href=\"")
.append("\" target=\"_top\">Configuration Reference Home</a></div>");
}
// Composition relations
@SuppressWarnings("unchecked")
@SuppressWarnings("unchecked")
// Aggregation properties
@SuppressWarnings("unchecked")
@SuppressWarnings("unchecked")
// Check if something to print in composition relations
// (even if the list not empty, it may contain only hidden relations)
boolean isCompRelsEmpty = true;
continue;
}
isCompRelsEmpty = false;
}
}
boolean isReverseCompRelsEmpty = true;
if (!reverseCompRels.isEmpty()) {
continue;
}
// check if it is not root
continue;
}
isReverseCompRelsEmpty = false;
}
}
// Check if something to print in reverse aggregation relations
// (even if the list not empty, it may contain only relations from
// hidden component)
boolean isReverseAggregPropsEmpty = true;
if (!reverseAggregProps.isEmpty()) {
@SuppressWarnings("unchecked")
continue;
}
isReverseAggregPropsEmpty = false;
}
}
}
//
// Relations FROM this component
//
heading3("Relations From this Component");
}
if (!isCompRelsEmpty) {
"The following components have a direct COMPOSITION relation FROM " +
continue;
}
beginList();
".html");
endList();
}
}
if (!aggregProps.isEmpty()) {
"The following components have a direct AGGREGATION relation FROM " +
}
beginList();
endList();
}
}
//
// Relations TO this component
//
if (!isReverseCompRelsEmpty || !isReverseAggregPropsEmpty) {
heading3("Relations To this Component");
}
{
"The following components have a direct COMPOSITION relation TO " +
beginList();
endList();
}
}
if (!isReverseAggregPropsEmpty) {
"The following components have a direct AGGREGATION relation TO " +
}
beginList();
".html");
endList();
}
}
}
private void generateProperty(
// Property name
"propertyname");
// Property table
startTable();
tableRow("Description",
// Default value
tableRow("Multi-valued",
} else {
}
" must be disabled and re-enabled for changes to this setting " +
"to take effect";
actionStr = "Restart the server";
actionStr = "None";
}
}
} else {
}
} else {
}
endTable();
}
.append(" <tr>\n")
.append(" <th>Basic Properties:</th>\n")
.append(" <th>Advanced Properties:</th>\n")
.append(" </tr>\n");
for (int ii=0;
ii++) {
if (basicPropName != null) {
+ basicPropName + "</a></td>\n";
basicHtmlCell = " <td> None</td>\n";
// Case of nb of basic props < nb of advanced props
basicHtmlCell = " <td></td>\n";
}
if (advancedPropName != null) {
advancedHtmlCell = " <td> None</td>\n";
}
}
}
//------------------------------------------------------------------------
// LDAP mapping
//------------------------------------------------------------------------
heading3("LDAP Mapping");
"Each configuration property can be mapped to a specific " +
"LDAP attribute under the \"cn=config\" entry. " +
"The mappings that follow are provided for information only. " +
"In general, you should avoid changing the server configuration " +
"by manipulating the LDAP attributes directly.");
// Managed object table
startTable();
superior = "top";
} else {
superior =
} else {
}
}
} else {
}
endTable();
newline();
// Properties table
startTable();
}
endTable();
}
private void genManagedObjectList(
+ " Configuration Reference - Components View");
viewHelp("This view provides a list of all configuration components, " +
"in alphabetical order.");
newline();
}
.append("</p>\n");
}
htmlFooter();
}
private void genPropertiesIndex() {
// Build a sorted list of (property name + its managed object name)
}
}
}
MAIN_FRAME, "#666");
}
htmlBuff = new StringBuffer();
" Configuration Reference - Properties View");
viewHelp("This view provides a list of all configuration properties, " +
"in alphabetical order, and indicates the configuration component to " +
"which each property applies.");
newline();
htmlFooter();
}
private void genWelcomePage() {
" Configuration Reference - Welcome");
heading2("About This Reference");
paragraph("This reference " +
" configuration properties that can be manipulated " +
"with the dsconfig command.");
paragraph("Configuration components are grouped according to the area of " +
"the server in which they are used, as follows:");
beginList();
}
endList();
"For ease of reference, the configuration is described on multiple " +
"tabs. These tabs provide alternative views of the configuration " +
"components:");
beginList();
bullet("The <strong>Inheritance</strong> view represents the inheritance " +
"relationships between configuration components. A sub-component " +
"inherits all of the properties of its parent component.");
bullet("The <strong>Structure</strong> view represents the structural " +
"relationships between components and indicates how certain components " +
"can exist only within container components. When a container " +
"component is deleted, all of the components within it are also " +
"deleted.");
"The <strong>Components</strong> view provides an alphabetical list " +
"of all configuration components.");
"The <strong>Properties</strong> view provides an alphabetical list " +
"of all configuration properties, and indicates the configuration " +
"component to which each property applies.");
endList();
newline();
paragraph("When you set up " +
", certain components are created in the " +
"configuration by default. These components are configured with " +
"specific values, which are not necessarily the same as the " +
"\"default values\" of new components that you create using dsconfig. " +
"The \"default values\" listed in this document refer to the values " +
"of the new components that you create using dsconfig.");
htmlFooter();
}
private void genMainTopPage() {
" Configuration Reference - Main Top");
// "Home" might be depend on where this is published.
/*
htmlBuff.append("<div class=\"breadcrumb\"><span class=\"pageactions\">" +
"<a href=\"" + OpenDJHome + "\" target=\"_parent\">" +
"<span style=\"font-size: 12px;\">« </span>" +
"Back to " +
DynamicConstants.PRODUCT_NAME + " Home</a></span> </div>\n");
*/
" </span> </div>\n");
"width=\"100%\">\n");
" Configuration Reference</h2></td>\n");
/*
htmlBuff.append(" <td valign=\"bottom\" width=\"10%\">" +
"<a href=\"" + OpenDJHome + "\" target=\"_parent\">" +
"<img src=\"opendj_logo_sm.png\" alt=\"OpenDJ Logo\" align=\"bottom\" " +
"border=\"0\" height=\"33\" width=\"114\"></a></td>\n");
*/
"<img src=\"opendj_logo_sm.png\" alt=\"OpenDJ Logo\" align=\"bottom\" " +
"border=\"0\" height=\"33\" width=\"114\"></td>\n");
htmlFooter();
}
private void genIndexPage() {
"frameborder=\"yes\" border=\"1\" bordercolor=\"#333333\">\n");
"id=\"topFrame\" border=\"1\" title=\"topFrame\" scrolling=\"no\">\n");
"border=\"1\" " +
"framespacing=\"1\">\n");
"name=\"leftFrame\" id=\"leftFrame\" title=\"leftFrame\" " +
"scrolling=\"auto\">\n");
"\" name=\"mainFrame\" " +
"id=\"mainFrame\" title=\"mainFrame\" scrolling=\"auto\">\n");
}
return baseDn;
} else {
// Check the parent relation
}
// check its superior
} else {
}
return null;
}
@SuppressWarnings("unchecked")
// Create a visitor for performing syntax specific processing.
// Rather than return a link that is coupled to a site location,
// assume that readers can find ACI syntax in the documentation.
// ACI syntax being difficult to understand and to explain,
// it is better not to have to maintain a separate page, either.
return "An ACI syntax"; // getLink("An ACI Syntax", aciSyntaxPage);
}
public String visitAggregation(
}
public String visitAttributeType(
return "The name of an attribute type defined in the server schema.";
}
}
"A java class that implements or extends the class(es) :";
}
return classStr;
}
}
return retStr;
}
". ";
if (prop.isAllowUnlimited()) {
durationStr += "A value of \"-1\" or \"unlimited\" for no limit. ";
}
durationStr += "Maximum unit is \"" +
}
}
return durationStr;
}
}
}
return enumStr;
}
}
if (prop.isAllowUnlimited()) {
intStr += " A value of \"-1\" or \"unlimited\" for no limit.";
}
}
return intStr;
}
return "An IP address";
}
public String visitIPAddressMask(
return "An IP address mask";
}
}
}
if (prop.isAllowUnlimited()) {
sizeStr += " A value of \"-1\" or \"unlimited\" for no limit.";
}
return sizeStr;
}
}
return retStr;
}
return "Unknown";
}
};
// Invoke the visitor against the property definition.
}
@SuppressWarnings("unchecked")
if (defaultBehav instanceof UndefinedDefaultBehaviorProvider) {
defValueStr = "None";
} else if (defaultBehav instanceof DefinedDefaultBehaviorProvider) {
}
} else if (defaultBehav instanceof AliasDefaultBehaviorProvider) {
} else if
(defaultBehav instanceof RelativeInheritedDefaultBehaviorProvider) {
} else if
(defaultBehav instanceof AbsoluteInheritedDefaultBehaviorProvider) {
}
return defValueStr;
}
return null;
}
{
continue;
}
}
return map;
}
return null;
}
}
return map;
}
return null;
}
}
return map;
}
private void horizontalLine() {
}
private void endTable() {
}
}
}
}
}
}
str +
}
}
}
}
return "<html>\n" +
"<head>\n" +
"<meta http-equiv=\"content-type\"\n" +
"</head>\n";
}
/** Add a Tab Menu, the active tab is the one given as parameter. */
"<div class=\"tabmenu\"> " +
"<span><a " +
" title=\"Inheritance View of Components\">Inheritance</a></span> " +
"<span><a " +
" title=\"Relational View of Components\">Structure</a></span> " +
"<span><a " +
" title=\"Alphabetical Index of Components\">Components</a></span> " +
"<span><a " +
" title=\"Alphabetical Index of Properties\" >Properties</a></span>" +
"</div>" +
"\n"
);
}
}
}
return "<a " +
">"
+ str + "</a>";
}
}
}
} else if (inList) {
htmlStr += "<li>";
}
htmlStr += "</div>";
} else if (inList) {
htmlStr += "</li>";
}
if (!inList) {
htmlStr += "<br>";
}
}
private void newline() {
getNewLine());
}
private String getNewLine() {
return "<br>\n";
}
if (description != null) {
}
}
}
}
if (getIndentPixels() > 0) {
}
styleStr = "style=\"font-weight: bold;\"";
styleStr = "style=\"font-style: italic;\"";
}
}
htmlBuff.append("<p ").append(indentStr).append(" ").append(styleStr).append(" ").append(classStr).append(">")
.append("</p>\n");
}
private int getIndentPixels() {
return ind * 40;
}
private void startTable() {
.append("style=\"width: 100%; text-align: left;\"")
.append("border=\"1\"")
.append("cellpadding=\"1\"")
.append("cellspacing=\"0\"")
.append(">\n");
}
/**
* Generate a "friendly" name from a string :
* '-' and '_' replaced by space
* first letter of a word in uppercase
*/
if (ii>0) {
retStr += " ";
}
}
return retStr;
}
"<tr>\n");
.append("vertical-align: top; ")
.append("\">")
.append("<br></td>");
}
"</tr>\n");
}
/**
* Text style.
*/
private enum TextStyle {
}
private void beginList() {
inList = true;
listLevel++;
"<ul>\n");
}
private void endList() {
listLevel--;
if (listLevel == 0) {
inList = false;
}
"</ul>\n");
}
private void htmlFooter() {
}
.append("</p>")
.append("\n");
}
// Write the html buffer in a file
try {
} catch (Exception e) {
e.printStackTrace();
}
// re-init html buffer
htmlBuff = new StringBuffer();
}
/** Relation List from RootConfiguration. */
/** Managed object list. */
catTopMoList = new TreeMap<>();
private final int ind = 0;
private static String generationDir;
private static boolean ldapMapping;
private static String OpenDJWiki;
private static String OpenDJHome;
private static String aciSyntaxPage;
private static String durationSyntaxPage;
private boolean inList;
private int listLevel;
}