/*
 * Copyright 2014 Texas A&M Engineering Experiment Station
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package edu.tamu.tcat.account.token;

/**
 * An API for creating and unpacking tokens of a particular "payload type".
 * <p>
 * Implementations should be configured with the expiration time. Multiple {@link TokenService}s
 * may be used within the same application.
 *
 * @param <PayloadType>
 */
public interface TokenService<PayloadType>
{
   /**
    * A construct representing a secure token's data, including the token payload itself
    * and its expiration time.
    */
   interface TokenData<PT>
   {
      /**
       * Get the unencrypted payload encrypted into this token.
       */
      PT getPayload();
      
      /** The (encrypted) token. This typically has the expiration time embedded which is used
       * in validation when processing.
       */
      String getToken();
      
      /**
       * A string representation of the expiration date/time of the associated token. The
       * returned value must be human-readable, and must contain date, time, and timezone information.
       * The implementation may decide whether it follows a standard (e.g. ISO-8601 or RFC-1123)
       * representation or is arbitrarily constructed.
       * 
       * @deprecated This method should be replaced with one that returns date components such
       *             as Java 8 ZonedDateTime or Instant to allow the calling code to format into
       *             an appropriate string representation as necessary.
       */
      @Deprecated
      String getExpireStr();
   }
   
   /**
    * Create a {@link TokenData} from a payload. The token may be used to
    * construct headers or cookies for client/server applications.
    * 
    * @param id The payload to encode in the token.
    * @return A new data instance containing an expiring token's (encrypted) content and
    *         expiration timestamp.
    * @throws AccountTokenException If the token cannot be created.
    */
   TokenData<PayloadType> createTokenData(PayloadType uuid) throws AccountTokenException;
   
   /**
    * Process the (encrypted) token string from the client. The string should be one previously
    * accessed from {@link TokenData#getToken()} from a {@link TokenData} constructed by this
    * instance using {@link #createTokenData(Object)}.
    * <p>
    * During token processing, certain validation is performed such as decryption and expiration timestamp
    * validation. If the token was not generated by this service, it may not unpack properly.
    * 
    * @param token The (encrypted) token to read.
    * @return The payload contained in the token.
    * @throws AccountTokenException If the token cannot be unpacked.
    */
   PayloadType unpackToken(String token) throws AccountTokenException;
   
   /**
    * Provide a Class representing {@code <PayloadType>}. This is used to validate this service can handle
    * type of payload available when both are retrieved anonymously.
    * 
    * @return The payload type. Does not return {@code null}
    */
   Class<PayloadType> getPayloadType();
}

@@ -238,17 +238,16 @@
 se at%0A *
- 
 %0A *     
@@ -291,17 +291,16 @@
 E-2.0%0A *
- 
 %0A * Unle
@@ -655,16 +655,49 @@
 token;%0A%0A
+import java.time.ZonedDateTime;%0A%0A
 /**%0A * A
@@ -1261,30 +1261,24 @@
 tPayload();%0A
-      
 %0A      /** T
@@ -1436,22 +1436,16 @@
 oken();%0A
-      
 %0A      /
@@ -1796,25 +1796,24 @@
 ed.%0A       *
- 
 %0A       * @d
@@ -1826,249 +1826,560 @@
 ted 
-This method should be replaced with one that returns date components such
+Use %7B@link #getExpiration()%7D. This method is deprecated due to allowing too much%0A       *             flexibility to the point of being arbitrary.%0A       */%0A      @Deprecated%0A      default String getExpireStr()%0A      %7B%0A         throw new UnsupportedOperationException();
 %0A      
+%7D%0A%0A
  
-*
      
+/**%0A
        
- as Java 8 ZonedDateT
+* The expiration date/t
 ime o
-r Instant to allow the calling code to format into%0A       *             an appropriate string representation as necessary
+f the associated token. The returned value contains date,%0A       * time, and timezone information. Callers then have the option to format to a standard%0A       * (e.g. ISO-8601 or RFC-1123) representation for further consumption
 .%0A  
@@ -2388,65 +2388,173 @@
    *
-/
 %0A
+ 
       
-@Deprecated%0A      String getExpireStr();
+* @return%0A       * @since 1.1%0A       */%0A      default ZonedDateTime getExpiration()%0A      %7B%0A         throw new UnsupportedOperationException();%0A      %7D
 %0A   %7D%0A
-   
 %0A   
@@ -2699,25 +2699,24 @@
 tions.%0A    *
- 
 %0A    * @para
@@ -3038,35 +3038,32 @@
 TokenException;%0A
-   
 %0A   /**%0A    * Pr
@@ -3507,33 +3507,32 @@
  properly.%0A    *
- 
 %0A    * @param to
@@ -3763,19 +3763,16 @@
 eption;%0A
-   
 %0A   /**%0A
@@ -3952,17 +3952,16 @@
 y.%0A    *
- 
 %0A    * @

Implement expiration providing ZonedDateTime