001/*
002 * oauth2-oidc-sdk
003 *
004 * Copyright 2012-2016, Connect2id Ltd and contributors.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.oauth2.sdk.token;
019
020
021import com.nimbusds.oauth2.sdk.id.Identifier;
022import net.minidev.json.JSONObject;
023
024import java.util.HashMap;
025import java.util.Map;
026import java.util.Set;
027
028
029/**
030 * The base abstract class for access, refresh and other tokens. Concrete
031 * extending classes should be immutable.
032 * 
033 * <p>Related specifications:
034 *
035 * <ul>
036 *     <li>OAuth 2.0 (RFC 6749)
037 * </ul>
038 */
039public abstract class Token extends Identifier {
040        
041        
042        private static final long serialVersionUID = 1797025947209047077L;
043
044
045        /**
046         * Additional custom parameters.
047         */
048        private Map<String, Object> customParams;
049        
050        
051        /**
052         * Creates a new token with the specified value.
053         *
054         * @param value The token value. Must not be {@code null} or empty 
055         *              string.
056         */
057        protected Token(final String value) {
058
059                super(value);
060        }
061
062
063        /**
064         * Creates a new token with a randomly generated value of the specified 
065         * byte length, Base64URL-encoded.
066         *
067         * @param byteLength The byte length of the value to generate. Must be
068         *                   greater than one.
069         */
070        protected Token(final int byteLength) {
071        
072                super(byteLength);
073        }
074        
075        
076        /**
077         * Creates a new token with a randomly generated 256-bit (32-byte) 
078         * value, Base64URL-encoded.
079         */
080        protected Token() {
081        
082                super();
083        }
084
085
086        /**
087         * Returns the token parameter names included in the JSON object, as
088         * required for the composition of an access token response. See OAuth
089         * 2.0 (RFC 6749), section 5.1.
090         *
091         * @return The token parameter names.
092         */
093        public abstract Set<String> getParameterNames();
094
095
096        /**
097         * Returns the token parameters as a JSON object, as required for the
098         * composition of an access token response. See OAuth 2.0 (RFC 6749), 
099         * section 5.1.
100         *
101         * <p>Note that JSONObject implements {@literal Map&lt;String,Object&gt;}.
102         *
103         * <p>Example:
104         *
105         * <pre>
106         * {
107         *   "access_token"      : "2YotnFZFEjr1zCsicMWpAA",
108         *   "token_type"        : "example",
109         *   "expires_in"        : 3600,
110         *   "example_parameter" : "example_value"
111         * }
112         * </pre>
113         *
114         * @return The token parameters as a JSON object.
115         */
116        public abstract JSONObject toJSONObject();
117
118
119        /**
120         * Returns the additional custom parameters.
121         *
122         * @return The custom parameters, empty map if none.
123         */
124        public Map<String, Object> getCustomParameters() {
125
126                if (customParams == null) {
127                        // Lazy init
128                        customParams = new HashMap<>();
129                }
130
131                return customParams;
132        }
133}