Skip to content

Commit

Permalink
Add javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
Trever Shick committed Nov 12, 2016
1 parent ef670b6 commit d019412
Show file tree
Hide file tree
Showing 38 changed files with 709 additions and 188 deletions.
83 changes: 77 additions & 6 deletions core/src/main/java/io/shick/jsoup/BasicWhitelistConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@

import org.jsoup.safety.Whitelist;

/**
* <p>BasicWhitelistConfiguration class.</p>
*
* @author Trever Shick - trever@shick.io
*/
public class BasicWhitelistConfiguration implements MutableWhitelistConfiguration {

private List<String> tags = null;
Expand All @@ -44,6 +49,9 @@ private Map<String, Map<String, List<String>>> protocols() {
return Optional.ofNullable(protocols).orElseGet(Collections::emptyMap);
}

/**
* {@inheritDoc}
*/
public MutableWhitelistConfiguration allowTag(String tagName) {
if (tags == null) {
tags = new ArrayList();
Expand All @@ -52,32 +60,53 @@ public MutableWhitelistConfiguration allowTag(String tagName) {
return this;
}

/**
* {@inheritDoc}
*/
public void allowedTags(Consumer<String> fn) {
tags().forEach(fn);
}

/**
* {@inheritDoc}
*/
public void allowedAttributes(BiConsumer<String, List<String>> fn) {
this.attributes().forEach(fn);
}

/**
* {@inheritDoc}
*/
public void enforcedAttributes(BiConsumer<String, Map<String, String>> fn) {
enforcedAttributes().forEach(fn);
}

/**
* {@inheritDoc}
*/
public void allowedProtocols(BiConsumer<String, Map<String, List<String>>> fn) {
protocols().forEach(fn);
}

/**
* {@inheritDoc}
*/
public boolean allowsTag(String tagName) {
requireTagName(tagName);
return tags().contains(tagName);
}

/**
* {@inheritDoc}
*/
public boolean hasAllowedAttributes(String tagName) {
requireTagName(tagName);
return attributes().containsKey(tagName);
}

/**
* {@inheritDoc}
*/
public MutableWhitelistConfiguration allowAttribute(String tagName, String attrName) {
requireTagName(tagName);
requireAttrName(attrName);
Expand All @@ -88,29 +117,44 @@ public MutableWhitelistConfiguration allowAttribute(String tagName, String attrN
return this;
}

/**
* {@inheritDoc}
*/
public boolean allowsAttribute(String tagName, String attrName) {
requireAttrName(attrName);
return hasAllowedAttributes(tagName)
&& attributes().get(tagName).contains(attrName);
}

/**
* {@inheritDoc}
*/
public boolean hasEnforcedAttributes(String tagName) {
requireTagName(tagName);
return enforcedAttributes().containsKey(tagName);
}

/**
* {@inheritDoc}
*/
public boolean enforcesAttribute(String tagName, String attrName) {
requireAttrName(attrName);
return hasEnforcedAttributes(tagName)
&& enforcedAttributes().get(tagName).get(attrName) != null;
}

/**
* {@inheritDoc}
*/
public boolean enforcesAttribute(String tagName, String attrName, String enforcedValue) {
requireEnforcedValue(enforcedValue);
return enforcesAttribute(tagName, attrName)
&& enforcedAttributes().get(tagName).get(attrName).equals(enforcedValue);
}

/**
* {@inheritDoc}
*/
public MutableWhitelistConfiguration enforceAttribute(String tagName, String attrName, String enforcedValue) {
requireTagName(tagName);
requireAttrName(attrName);
Expand All @@ -122,17 +166,26 @@ public MutableWhitelistConfiguration enforceAttribute(String tagName, String att
return this;
}

/**
* {@inheritDoc}
*/
public boolean hasAllowedProtocols(String tagName) {
requireTagName(tagName);
return protocols().containsKey(tagName);
}

/**
* {@inheritDoc}
*/
public boolean hasAllowedProtocols(String tagName, String attrName) {
requireAttrName(attrName);
return hasAllowedProtocols(tagName)
&& protocols().get(tagName).containsKey(attrName);
}

/**
* {@inheritDoc}
*/
public MutableWhitelistConfiguration allowProtocol(String tagName, String attrName, String protocol) {
requireTagName(tagName);
requireAttrName(attrName);
Expand All @@ -145,26 +198,38 @@ public MutableWhitelistConfiguration allowProtocol(String tagName, String attrNa
return this;
}

/**
* {@inheritDoc}
*/
public boolean allowsProtocol(String tagName, String attrName, String protocol) {
requireProtocol(protocol);
return hasAllowedProtocols(tagName, attrName)
&& protocols().get(tagName).get(attrName).contains(protocol);
}

/**
* {@inheritDoc}
*/
@Override
public Whitelist apply(Whitelist in) {
applyTags(in);
applyAttributes(in);
applyEnforcedAttributes(in);
applyProtocols(in);
return in;
public Whitelist apply(Whitelist whitelist) {
applyTags(whitelist);
applyAttributes(whitelist);
applyEnforcedAttributes(whitelist);
applyProtocols(whitelist);
return whitelist;
}

/**
* {@inheritDoc}
*/
@Override
public Whitelist whitelist() {
return apply(Whitelist.none());
}

/**
* {@inheritDoc}
*/
@Override
public boolean equals(Object o) {
if (this == o) {
Expand All @@ -180,11 +245,17 @@ public boolean equals(Object o) {
Objects.equals(protocols(), that.protocols());
}

/**
* {@inheritDoc}
*/
@Override
public int hashCode() {
return Objects.hash(tags(), attributes(), enforcedAttributes(), protocols());
}

/**
* {@inheritDoc}
*/
@Override
public String toString() {
final StringBuilder sb = new StringBuilder("BasicWhitelistConfiguration{");
Expand Down
34 changes: 34 additions & 0 deletions core/src/main/java/io/shick/jsoup/MutableWhitelistConfiguration.java
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,45 @@
package io.shick.jsoup;

/**
* <p>MutableWhitelistConfiguration interface.</p>
*
* @author Trever Shick - trever@shick.io
*/
public interface MutableWhitelistConfiguration extends WhitelistConfiguration {
/**
* <p>Add an allowed tag to the configuration</p>
*
* @param tagName (non null) an HTML tag name
* @return a {@link io.shick.jsoup.MutableWhitelistConfiguration} object.
*/
MutableWhitelistConfiguration allowTag(String tagName);

/**
* <p>Add an enforced attribute value to the configuration</p>
*
* @param tagName (non null) an HTML tag name
* @param attrName (non null) an HTML attribute name
* @param enforcedValue (non null) the string value for the specified attribute.
* @return a {@link io.shick.jsoup.MutableWhitelistConfiguration} object.
*/
MutableWhitelistConfiguration enforceAttribute(String tagName, String attrName, String enforcedValue);

/**
* <p>Add an allowed protocol to the configuration</p>
*
* @param tagName (non null) an HTML tag name
* @param attrName (non null) an HTML attribute name
* @param protocol (non null) a protocol like 'https' or 'http'
* @return a {@link io.shick.jsoup.MutableWhitelistConfiguration} object.
*/
MutableWhitelistConfiguration allowProtocol(String tagName, String attrName, String protocol);

/**
* <p>Add an allowed attribute to the configuration</p>
*
* @param tagName (non null) an HTML tag name
* @param attrName (non null) an HTML attribute name
* @return a {@link io.shick.jsoup.MutableWhitelistConfiguration} object.
*/
MutableWhitelistConfiguration allowAttribute(String tagName, String attrName);
}
108 changes: 102 additions & 6 deletions core/src/main/java/io/shick/jsoup/WhitelistConfiguration.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,35 +7,131 @@

import org.jsoup.safety.Whitelist;

/**
* <p>WhitelistConfiguration interface.</p>
*
* @author Trever Shick - trever@shick.io
*/
public interface WhitelistConfiguration {

/**
* <p><em>fn</em> will be called once for each allowed tag.</p>
*
* @param fn (non null) a {@link java.util.function.Consumer} object.
*/
void allowedTags(Consumer<String> fn);

/**
* <p>
* <em>fn</em> will be called once for each allowed tag
* with the allowed attributes as the second argument, for
* example <em>accept('a',['href','rel'])</em>
* </p>
*
* @param fn a {@link java.util.function.BiConsumer} object.
*/
void allowedAttributes(BiConsumer<String, List<String>> fn);

void enforcedAttributes(BiConsumer<String, Map<String,String>> fn);

void allowedProtocols(BiConsumer<String, Map<String,List<String>>> fn);

/**
* <p>
* <em>fn</em> will be called once for each allowed tag
* with the enforced attributes map as the second argument, for
* example <em>accept('a',{ 'rel':'nofollow' })</em>
* </p>
*
* @param fn a {@link java.util.function.BiConsumer} object.
*/
void enforcedAttributes(BiConsumer<String, Map<String, String>> fn);

/**
* <p>
* <em>fn</em> will be called once for each allowed tag
* with the allowed protocols as the second argument, for
* example <em>accept('a',{ 'href':['http','https'] })</em>
* </p>
*
* @param fn a {@link java.util.function.BiConsumer} object.
*/
void allowedProtocols(BiConsumer<String, Map<String, List<String>>> fn);

/**
* @param tagName (non null) a valid HTML tag name
* @return true if <em>tagName</em> is allowed
*/
boolean allowsTag(String tagName);

/**
* @param tagName (non null) a valid HTML tag name
* @return true if <em>tagName</em> has allowed attributes.
*/
boolean hasAllowedAttributes(String tagName);

/**
* @param tagName (non null) a valid HTML tag name
* @param attrName (non null) a valid HTML attribute name
* @return true if <em>tagName</em> allows <em>attrName</em>
*/
boolean allowsAttribute(String tagName, String attrName);

/**
* @param tagName (non null) a valid HTML tag name
* @return true if <em>tagName</em> has any enforced attributes.
*/
boolean hasEnforcedAttributes(String tagName);

/**
* @param tagName (non null) a valid HTML tag name
* @param attrName (non null) a valid HTML attribute name
* @return true if <em>tagName</em> enforces a value for <em>attrName</em>
*/
boolean enforcesAttribute(String tagName, String attrName);

/**
* @param tagName (non null) a valid HTML tag name
* @param attrName (non null) a valid HTML attribute name
* @param enforcedValue a {@link java.lang.String} object.
* @return true if <em>tagName</em> enforces the value <em>enforcedValue</em> for <em>attrName</em>
*/
boolean enforcesAttribute(String tagName, String attrName, String enforcedValue);

/**
* @param tagName (non null) a valid HTML tag name
* @return true if <em>tagName</em> has any configured allowed protocols
*/
boolean hasAllowedProtocols(String tagName);

/**
* @param tagName (non null) a valid HTML tag name
* @param attrName (non null) a valid HTML attribute name
* @return true if <em>tagName</em>'s <em>attrName</em> attribute has allowed protocols.
*/
boolean hasAllowedProtocols(String tagName, String attrName);

/**
* <p>allowsProtocol.</p>
*
* @param tagName (non null) a valid HTML tag name
* @param attrName (non null) a valid HTML attribute name
* @param protocol (non null) a protocol like 'https' or 'http'
* @return true if <em>tagName</em>'s <em>attrName</em> attribute allows <em>protocol</em>
*/
boolean allowsProtocol(String tagName, String attrName, String protocol);

Whitelist apply(Whitelist in);

/**
* <p>Applies all the configured rules to the supplied {@link Whitelist} instance.</p>
*
* @param whitelist a {@link org.jsoup.safety.Whitelist} object.
* @return a configured {@link org.jsoup.safety.Whitelist} instance.
*/
Whitelist apply(Whitelist whitelist);

/**
* <p>
* Constructs an empty {@link Whitelist} and applies the configured
* rules to it.
* </p>
*
* @return a configured {@link org.jsoup.safety.Whitelist} object.
*/
Whitelist whitelist();
}

0 comments on commit d019412

Please sign in to comment.