File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\markup\MarkupFormatter.java.html

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2010, CloudBees, Inc.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24 package hudson.markup;
25
26 import hudson.ExtensionPoint;
27 import hudson.model.AbstractDescribableImpl;
28 import hudson.util.HttpResponses;
29 import jenkins.model.Jenkins;
30 import org.kohsuke.stapler.HttpResponse;
31 import org.kohsuke.stapler.QueryParameter;
32 import org.kohsuke.stapler.StaplerRequest;
33 import org.kohsuke.stapler.StaplerResponse;
34
35 import javax.servlet.ServletException;
36 import java.io.IOException;
37 import java.io.StringWriter;
38 import java.io.Writer;
39
40 /**
41 * Generalization of a function that takes text with some markup and converts that to HTML.
42 * Such markup is often associated with Wiki.
43 *
44 * <p>
45 * Use of markup, as opposed to using raw HTML, ensures certain degree of security.
46 *
47 * <p>
48 * This is an extension point in Hudson, allowing plugins to implement different markup formatters.
49 *
50 * <p>
51 * Implement the following methods to enable and control CodeMirror syntax highlighting
52 * public String getCodeMirrorMode() // return null to disable CodeMirror dynamically
53 * public String getCodeMirrorConfig()
54 *
55 * <h2>Views</h2>
56 * <p>
57 * This extension point must have a valid <tt>config.jelly</tt> that feeds the constructor.
58 *
59 * TODO: allow {@link MarkupFormatter} to control the UI that the user uses to edit.
60 *
61 * @author Kohsuke Kawaguchi
62 * @since 1.391
63 * @see jenkins.model.Jenkins#getMarkupFormatter()
64 */
65 public abstract class MarkupFormatter extends AbstractDescribableImpl<MarkupFormatter> implements ExtensionPoint {
66 /**
67 * Given the text, converts that to HTML according to whatever markup rules implicit in the implementation class.
68 *
69 * <p>
70 * Multiple threads can call this method concurrently with different inputs.
71 *
72 * @param output
73 * Formatted HTML should be sent to this output.
74 */
75 public abstract void translate(String markup, Writer output) throws IOException;
76
77 public final String translate(String markup) throws IOException {
78 StringWriter w = new StringWriter();
79 translate(markup,w);
80 return w.toString();
81 }
82
83 /**
84 * Gets the URL of the help file. This help will shown next to the text area of the description,
85 * and is ideal of describing what the allowed syntax is.
86 *
87 * By default, we look for colocated help-syntax.html.
88 *
89 * @since 1.398
90 * @return null
91 * If there's no help file.
92 */
93 public String getHelpUrl() {
94 return getDescriptor().getHelpFile("syntax");
95 }
96
97 @Override
98 public MarkupFormatterDescriptor getDescriptor() {
99 return (MarkupFormatterDescriptor)super.getDescriptor();
100 }
101
102 /**
103 * Generate HTML for preview, using markup formatter.
104 * Can be called from other views.
105 */
106 public HttpResponse doPreviewDescription(@QueryParameter String text) throws IOException {
107 StringWriter w = new StringWriter();
108 translate(text, w);
109 return HttpResponses.html(w.toString());
110 }
111 }
112