# HG changeset patch # User Ingo Weinzierl # Date 1270026545 0 # Node ID 0dc115cbef0dbf5c817504903f8c2cefd8be98c6 # Parent e8a9e84a03288f67a89dd16ecf1b01069280ebb6 Added javadoc for artifact package. gnv-artifacts/trunk@871 c6561f87-3c4e-4783-a992-168aeb5c3f6f diff -r e8a9e84a0328 -r 0dc115cbef0d gnv-artifacts/ChangeLog --- a/gnv-artifacts/ChangeLog Wed Mar 31 08:01:56 2010 +0000 +++ b/gnv-artifacts/ChangeLog Wed Mar 31 09:09:05 2010 +0000 @@ -1,3 +1,12 @@ +2010-03-30 Ingo Weinzierl + + * src/main/java/de/intevation/gnv/artifacts/GNVArtifactFactory.java, + src/main/java/de/intevation/gnv/artifacts/GNVProductArtifactFactory.java, + src/main/java/de/intevation/gnv/artifacts/PreSettingArtifact.java, + src/main/java/de/intevation/gnv/artifacts/GNVArtifactBase.java, + src/main/java/de/intevation/gnv/artifacts/GNVDefaultArtifact.java: Added + JavaDoc for this package. + 2010-03-30 Ingo Weinzierl * src/main/java/de/intevation/gnv/chart/XMLChartTheme.java, diff -r e8a9e84a0328 -r 0dc115cbef0d gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactBase.java --- a/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactBase.java Wed Mar 31 08:01:56 2010 +0000 +++ b/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactBase.java Wed Mar 31 09:09:05 2010 +0000 @@ -55,6 +55,9 @@ import org.w3c.dom.NodeList; /** + * This is the major gnv artifact and handles the requests specified in + * {@link de.intevation.artifactdatabase.Artifact}. + * * @author Tim Englich * @author Ingo Weinzierl * @author Sascha L. Teichmann @@ -83,18 +86,39 @@ + XPATH_IDENTIFIER_REPLACE + "']"; + /** + * + */ public static final String XPATH_STATIC_NODE = "/art:result/art:ui/art:static"; + /** + * + */ public static final String XPATH_INPUT_DATA = "/art:action/art:data/art:input"; + /** + * + */ public static final String XPATH_INCLUDE_UI = "/art:action/art:include-ui"; + /** + * + */ public static final String XPATH_TARGET_NAME = "/art:action/art:target/@name"; + /** + * + */ public static final String XPATH_OUTPUT_NAME = "/art:action/art:out/@name"; + /** + * + */ public static final String XPATH_OUTPUT_PARAMS = "/art:action/art:out/art:params/art:input"; + /** + * + */ public static final String INITIAL_STATE = "product"; /** @@ -137,6 +161,15 @@ } + /** + * This method handles request for changing the current state of an + * artifact. It is possible to step forward, backward, or to the initial + * state for choosing a fis. + * + * @param target + * @param context + * @return + */ @Override public Document advance(Document target, CallContext context) { log.debug("GNVArtifactBase.advance()"); @@ -268,6 +301,14 @@ } + /** + * + * @param document + * @param nodeName + * @param state + * @param msg + * @return + */ protected Document createReport( Document document, String nodeName, @@ -292,6 +333,12 @@ } + /** + * Step back to the previous state specified by name. + * @param current + * @param name + * @return + */ protected State getPreviousState(State current, String name) { if (current == null) { return null; @@ -320,7 +367,12 @@ return false; } - public Document initialize (CallContext context) { + /** + * + * @param context + * @return + */ + public Document initialize(CallContext context) { Document result = XMLUtils.newDocument(); try { this.current.initialize(super.identifier, context); @@ -358,6 +410,11 @@ return result; } + /** + * Step forward to the next reachable state. + * @param current Current state. + * @return Reachable state. + */ protected State getNextReachableState(State current){ Iterator it = this.transitions.iterator(); String from = current.getID(); @@ -372,12 +429,22 @@ return null; } + /** + * + * @param document + * @return + */ protected String readStateName(Document document) { String returnValue = XMLUtils.xpathString( document, XPATH_TARGET_NAME, ArtifactNamespaceContext.INSTANCE); return returnValue; } + /** + * + * @param document + * @return + */ protected Node getConfigurationFragment(Document document) { log.debug("GNVArtifactBase.getConfigurationFragment"); String xpathQuery = XPATH_ARTIFACT_CONFIGURATION.replaceAll( @@ -395,6 +462,10 @@ } /** + * Insert new data included in target into the current state. + * @param target XML document which contains data. + * @param context CallContext + * @return XML document with success or error message. * @see de.intevation.artifactdatabase.DefaultArtifact#feed(org.w3c.dom.Document, * de.intevation.artifacts.CallContext) */ @@ -442,6 +513,10 @@ /** + * Describe the current artifact. + * @param data + * @param context + * @return The description of the current artifact. * @see de.intevation.artifactdatabase.DefaultArtifact#describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext) */ @Override @@ -458,6 +533,12 @@ } /** + * Initialse this artifact and insert some data if data + * contains necessary information for this artifact. + * @param identifier + * @param context + * @param factory + * @param data * @see de.intevation.artifactdatabase.DefaultArtifact#setup(java.lang.String, de.intevation.artifacts.ArtifactFactory, java.lang.Object, org.w3c.dom.Document) */ @Override @@ -508,6 +589,15 @@ } + /** + * Create the xml document returned in {@link #describe(org.w3c.dom.Document, + * de.intevation.artifacts.CallContext)} + * + * @param context + * @param uuid + * @param incudeUI + * @return + */ protected Document createDescibeOutput( CallContext context, String uuid, @@ -534,6 +624,14 @@ return document; } + /** + * Determine the wish to append the user interface description to the + * describe document. + * + * @param document + * @return True, if the user interface description should be appended, + * otherwise false. + */ protected boolean getIncludeUIFromDocument(Document document){ String value = XMLUtils.xpathString( document, XPATH_INCLUDE_UI, ArtifactNamespaceContext.INSTANCE); @@ -545,6 +643,12 @@ return includeUI; } + /** + * + * @param creator + * @param document + * @return + */ protected Element createRootNode( XMLUtils.ElementCreator creator, Document document @@ -554,6 +658,14 @@ return rootNode; } + /** + * Append information about the current artifact (uuid, hash). + * + * @param creator + * @param parent + * @param document + * @param documentType + */ protected void createHeader( XMLUtils.ElementCreator creator, Element parent, @@ -573,6 +685,15 @@ parent.appendChild(hashNode); } + /** + * Create the fis select box. + * + * @param artCreator + * @param creator + * @param document + * @param context + * @return + */ protected Element createSelectBox( XMLUtils.ElementCreator artCreator, XMLUtils.ElementCreator creator, @@ -619,6 +740,14 @@ } + /** + * Insert all reachable states into the describe document returned by + * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)} + * + * @param creator + * @param parent + * @param document + */ protected void createReachableStates( XMLUtils.ElementCreator creator, Element parent, @@ -651,6 +780,15 @@ } + /** + * Insert states which have been visited by this artifact into the xml + * document returned by {@link #describe(org.w3c.dom.Document, + * de.intevation.artifacts.CallContext)} + * + * @param creator + * @param parent + * @param state + */ protected void appendOldReachableStates( XMLUtils.ElementCreator creator, Element parent, @@ -670,6 +808,13 @@ } + /** + * Insert the current state into the xml document returned by + * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)} + * @param creator + * @param parent + * @param document + */ protected void createCurrentState( XMLUtils.ElementCreator creator, Element parent, @@ -681,6 +826,12 @@ parent.appendChild(stateNode); } + /** + * + * @param creator + * @param parent + * @param document + */ protected void createModel( XMLUtils.ElementCreator creator, Element parent, @@ -704,6 +855,15 @@ parent.appendChild(modelNode); } + /** + * Append the user interface description to the document returned by + * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)} + * @param creator XML element creator. + * @param parent New elements are appended to this node. + * @param document Current document. + * @param context CallContext + * @param uuid The uuid of the artifact. + */ protected void createUserInterface( XMLUtils.ElementCreator creator, Element parent, @@ -742,6 +902,13 @@ } + /** + * Append possible output targets to the document returned by + * {@link #describe(org.w3c.dom.Document, de.intevation.artifacts.CallContext)} + * @param creator Used to create xml elements. + * @param parent New elements are appended to this node. + * @param document The current document. + */ protected void createOutputs( XMLUtils.ElementCreator creator, Element parent, @@ -812,6 +979,12 @@ parent.appendChild(outputsNode); } + /** + * Parse input data from feed-document. + * @param document Feed-document + * @param xPath Path to input data. + * @return A collection with InputData objects. + */ protected Collection parseInputData(Document document, String xPath) { HashMap returnValue = null; @@ -842,6 +1015,13 @@ } /** + * Call an output target (e.g. chart, wms, etc.) + * @param format XML document which contains some further information about + * the desired output. + * @param outputStream Stream used for writing the output. + * @param context CallContext + * @throws IOException If an error occured while writing the result to the + * output stream. * @see de.intevation.artifactdatabase.DefaultArtifact#out(org.w3c.dom.Document, * java.io.OutputStream, de.intevation.artifacts.CallContext) */ @@ -863,6 +1043,11 @@ } } + /** + * + * @param document + * @return + */ protected static String readOutputType(Document document) { String value = XMLUtils.xpathString( document, XPATH_OUTPUT_NAME, ArtifactNamespaceContext.INSTANCE); @@ -870,10 +1055,19 @@ } + /** + * The the current product. + * @param product New product. + */ public void setProduct(Product product) { this.product = product; } + /** + * Call endOfLife of parent class and the current state. + * @param globalContext + */ + @Override public void endOfLife(Object globalContext) { super.endOfLife(globalContext); @@ -883,6 +1077,9 @@ } /** + * Retrieves a map with given InputData which have been inserted into the + * current artifact before the parameterization began. + * @return * @see de.intevation.gnv.artifacts.PreSettingArtifact#getPreSettings() */ public Map getPreSettings() { @@ -890,6 +1087,8 @@ } /** + * Set InputData which are used in later states. + * @param preSettings * @see de.intevation.gnv.artifacts.PreSettingArtifact#setPreSettings(java.util.Map) */ public void setPreSettings(Map preSettings) { @@ -899,4 +1098,4 @@ } } } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r e8a9e84a0328 -r 0dc115cbef0d gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactFactory.java --- a/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactFactory.java Wed Mar 31 08:01:56 2010 +0000 +++ b/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVArtifactFactory.java Wed Mar 31 09:09:05 2010 +0000 @@ -13,16 +13,28 @@ */ public class GNVArtifactFactory extends DefaultArtifactFactory { + /** + * + */ public static final String XPATH_PRODUCT_FACTORY = "artifact-factory"; private static Logger logger = Logger.getLogger(GNVArtifactFactory.class); + /** + * Constructor. + */ public GNVArtifactFactory() { } + /** + * + * @param document + * @param factoryNode Contains necessary information about the desired + * factory. + */ @Override public void setup(Document document, Node factoryNode) { super.setup(document, factoryNode); } } -// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8: +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : diff -r e8a9e84a0328 -r 0dc115cbef0d gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVDefaultArtifact.java --- a/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVDefaultArtifact.java Wed Mar 31 08:01:56 2010 +0000 +++ b/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVDefaultArtifact.java Wed Mar 31 09:09:05 2010 +0000 @@ -15,20 +15,37 @@ import org.w3c.dom.Element; /** + * The default gnv artifact. The only thing defined here is a method to append + * the selected fis to the describe document. + * * @author Ingo Weinzierl */ public class GNVDefaultArtifact extends DefaultArtifact { private static Logger logger = Logger.getLogger(GNVDefaultArtifact.class); + /** + * + */ public static final String EXCEPTION_NO_INPUT = "no.input.data"; + /** + * Constructor. + */ public GNVDefaultArtifact() { super(); } + /** + * Append the selected fis to the describe document. + * + * @param document + * @param staticNode + * @param context + * @param fisName + */ protected void appendFis( Document document, Element staticNode, @@ -83,3 +100,4 @@ staticNode.appendChild(selectNode); } } +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : \ No newline at end of file diff -r e8a9e84a0328 -r 0dc115cbef0d gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVProductArtifactFactory.java --- a/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVProductArtifactFactory.java Wed Mar 31 08:01:56 2010 +0000 +++ b/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/GNVProductArtifactFactory.java Wed Mar 31 09:09:05 2010 +0000 @@ -27,21 +27,43 @@ import org.w3c.dom.NodeList; /** + * This factory is called to create a {@link + * de.intevation.gnv.artifacts.fis.SelectProductArtifact} which lets the user + * select a product supported by the selected fis. + * * @author Ingo Weinzierl */ public class GNVProductArtifactFactory extends DefaultArtifactFactory { + /** + * + */ public static final String XPATH_REPLACE_NAME = "IDENTIFIER"; + /** + * + */ public static final String XPATH_PRODUCT_ARTIFACT = "artifact-database/artifacts/artifact[@name='"+XPATH_REPLACE_NAME+"']"; + /** + * + */ public static final String XPATH_PRODUCT = "products/product"; + /** + * + */ public static final String XPATH_PRODUCT_NAME = "@name"; + /** + * + */ public static final String XPATH_PRODUCT_FACTORY = "artifact-factory"; + /** + * + */ public static final String XPATH_PRODUCT_PARAMETER = "parameters/parameter"; private Logger logger = Logger.getLogger(GNVProductArtifactFactory.class); @@ -50,9 +72,21 @@ private Map products; + /** + * Constructor. + */ public GNVProductArtifactFactory() { } + /** + * Method to create an artifact. If the created artifact is from type + * ProxyArtifact, a further ProductSelectArtifact is created + * which becomes embedded into the ProxyArtifact. + * @param identifier UUID. + * @param context CallContext. + * @param data Some data. + * @return The created artifact. + */ @Override public Artifact createArtifact(String identifier, Object context, Document data) { @@ -71,6 +105,11 @@ return artifact; } + /** + * + * @param document + * @param factoryNode + */ @Override public void setup(Document document, Node factoryNode) { super.setup(document, factoryNode); @@ -98,11 +137,21 @@ } + /** + * + * @param name + * @return + */ public ArtifactFactory getArtifactFactoryByName(String name) { return (ArtifactFactory) productFactories.get(name); } + /** + * + * @param document + * @param products + */ protected void parseProductFactories(Document document, NodeList products) { int items = products.getLength(); @@ -144,6 +193,10 @@ } + /** + * Initialize all products supported by the current fis. + * @param productNode + */ protected void initializeProducts(Node productNode) { String productName = (String) XMLUtils.xpath( productNode, "@name", XPathConstants.STRING); @@ -173,3 +226,4 @@ } } } +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : \ No newline at end of file diff -r e8a9e84a0328 -r 0dc115cbef0d gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/PreSettingArtifact.java --- a/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/PreSettingArtifact.java Wed Mar 31 08:01:56 2010 +0000 +++ b/gnv-artifacts/src/main/java/de/intevation/gnv/artifacts/PreSettingArtifact.java Wed Mar 31 09:09:05 2010 +0000 @@ -5,13 +5,25 @@ import java.util.Map; /** + * This artifact is used to be fed before the parameterization has started. + * * @author Tim Englich * */ public interface PreSettingArtifact { + /** + * + * @return the InputData which have been inserted before parameterization + * has started. + */ Map getPreSettings(); + /** + * + * @param preSettings + */ void setPreSettings(Map preSettings); } +// vim:set ts=4 sw=4 si et sta sts=4 fenc=utf8 : \ No newline at end of file