001package com.nimbusds.jose;
002
003
004import java.util.Map;
005import java.util.Set;
006
007import net.minidev.json.JSONObject;
008
009import com.nimbusds.jose.util.Base64URL;
010
011
012/**
013 * Read-only view of a {@link Header header}.
014 *
015 * @author Vladimir Dzhuvinov
016 * @version $version$ (2013-05-07)
017 */
018public interface ReadOnlyHeader {
019
020
021        /**
022         * Gets the algorithm ({@code alg}) parameter.
023         *
024         * @return The algorithm parameter.
025         */
026        public Algorithm getAlgorithm();
027
028
029        /**
030         * Gets the type ({@code typ}) parameter.
031         *
032         * @return The type parameter, {@code null} if not specified.
033         */
034        public JOSEObjectType getType();
035
036
037        /**
038         * Gets the content type ({@code cty}) parameter.
039         *
040         * @return The content type parameter, {@code null} if not specified.
041         */
042        public String getContentType();
043
044
045
046        /**
047         * Gets the critical headers ({@code crit}) parameter.
048         *
049         * @return The names of the critical header parameters, empty set or
050         *         {@code null} if none.
051         */
052        public Set<String> getCriticalHeaders();
053
054
055        /**
056         * Gets a custom (non-reserved) parameter.
057         *
058         * @param name The name of the custom parameter. Must not be 
059         *             {@code null}.
060         *
061         * @return The custom parameter, {@code null} if not specified.
062         */
063        public Object getCustomParameter(final String name);
064
065
066        /**
067         * Gets the custom (non-reserved) parameters.
068         *
069         * @return The custom parameters, as a unmodifiable map, empty map if 
070         *         none.
071         */
072        public Map<String,Object> getCustomParameters();
073
074
075        /**
076         * Gets the names of all included parameters (reserved and custom) in 
077         * the header instance.
078         *
079         * @return The included parameters.
080         */
081        public Set<String> getIncludedParameters();
082
083
084        /**
085         * Returns a JSON object representation of the header. All custom
086         * parameters are included if they serialise to a JSON entity and 
087         * their names don't conflict with the reserved ones.
088         *
089         * @return The JSON object representation of the header.
090         */
091        public JSONObject toJSONObject();
092
093
094        /**
095         * Returns a JSON string representation of the header. All custom
096         * parameters will be included if they serialise to a JSON entity and 
097         * their names don't conflict with the reserved ones.
098         *
099         * @return The JSON string representation of the header.
100         */
101        public String toString();
102
103
104        /**
105         * Returns a Base64URL representation of the header. If the header was
106         * parsed always returns the original Base64URL (required for JWS
107         * validation and authenticated JWE decryption).
108         *
109         * @return The original parsed Base64URL representation of the header,
110         *         or a new Base64URL representation if the header was created
111         *         from scratch.
112         */
113        public Base64URL toBase64URL();
114}