1 /*
2 * Copyright (c) 2011-2022, jcabi.com
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met: 1) Redistributions of source code must retain the above
8 * copyright notice, this list of conditions and the following
9 * disclaimer. 2) Redistributions in binary form must reproduce the above
10 * copyright notice, this list of conditions and the following
11 * disclaimer in the documentation and/or other materials provided
12 * with the distribution. 3) Neither the name of the jcabi.com nor
13 * the names of its contributors may be used to endorse or promote
14 * products derived from this software without specific prior written
15 * permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
19 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
21 * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 * OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30 package com.jcabi.w3c;
31
32 import java.io.IOException;
33
34 /**
35 * Validator of CSS pages through W3C validation API.
36 *
37 * <p>Retrieve it from {@link ValidatorBuilder} and use like this:
38 *
39 * <pre> HtmlValidator validator = new ValidatorBuilder().css();
40 * ValidationResponse response = validator.validate(text);
41 * if (!response.valid()) {
42 * // report about a problem
43 * }</pre>
44 *
45 * <p>Sometimes this Jigsaw validator makes mistakes, sometimes you just need to
46 * use some IE-specific feature, which is not CSS compliant. In this case you
47 * may add comments to the document, at the end of every line you want to ignore
48 * during validation, for example:
49 *
50 * <pre> div.test {
51 * color: red;
52 * #position: 50%; /* JIGSAW: this is a IE_-related hack */
53 * }</pre>
54 *
55 * <p>You can also instruct the validator to ingore the entire file, by means
56 * of adding {@code JIGSAW IGNORE} comment anywhere in the text, for example:
57 *
58 * <pre> /* JIGSAW IGNORE: it's an experimental file */
59 * div.test {
60 * something-totally-incorrect:...
61 * }</pre>
62 *
63 * <p>Validation will happen anyway, but {@link ValidationResponse#valid()}
64 * will return {@code TRUE}. You will still be able to read errors and warnings
65 * from it, but it will be valid.
66 *
67 * <p>Objects of this interface should be immutable and thread-safe.
68 *
69 * @see <a href="http://jigsaw.w3.org/css-validator/api.html">W3C API, CSS</a>
70 * @see ValidatorBuilder
71 * @since 0.1
72 */
73 public interface Validator {
74
75 /**
76 * Validate and return validation response.
77 *
78 * <p>The method should never throw runtime exceptions, no matter what
79 * happened with the HTTP connection to the W3C server. It will return
80 * an invalid response, but will never throw.
81 *
82 * <p>This method expects content of a document which should be
83 * validated, not URL to the document
84 *
85 * @param content The HTML/CSS content to validate
86 * @return The response
87 * @throws IOException If fails
88 */
89 ValidationResponse validate(String content) throws IOException;
90
91 }