001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.encoders; 014 015import static org.apache.juneau.internal.CollectionUtils.*; 016 017import java.util.*; 018import java.util.concurrent.*; 019 020import org.apache.juneau.http.*; 021 022/** 023 * Represents the group of {@link Encoder encoders} keyed by codings. 024 * 025 * <h5 class='topic'>Description</h5> 026 * 027 * Maintains a set of encoders and the codings that they can handle. 028 * 029 * <p> 030 * The {@link #getEncoderMatch(String)} and {@link #getEncoder(String)} methods are then used to find appropriate 031 * encoders for specific <c>Accept-Encoding</c> and <c>Content-Encoding</c> header values. 032 * 033 * <h5 class='topic'>Match ordering</h5> 034 * 035 * Encoders are matched against <c>Accept-Encoding</c> strings in the order they exist in this group. 036 * 037 * <p> 038 * Adding new entries will cause the entries to be prepended to the group. 039 * This allows for previous encoders to be overridden through subsequent calls. 040 * 041 * <p> 042 * For example, calling <code>groupBuilder.append(E1.<jk>class</jk>,E2.<jk>class</jk>).append(E3.<jk>class</jk>, 043 * E4.<jk>class</jk>)</code> will result in the order <c>E3, E4, E1, E2</c>. 044 * 045 * <h5 class='section'>Example:</h5> 046 * <p class='bcode w800'> 047 * <jc>// Create an encoder group with support for gzip compression.</jc> 048 * EncoderGroup g = EncoderGroup.<jsm>create</jsm>().append(GzipEncoder.<jk>class</jk>).build(); 049 * 050 * <jc>// Should return "gzip"</jc> 051 * String matchedCoding = g.findMatch(<js>"compress;q=1.0, gzip;q=0.8, identity;q=0.5, *;q=0"</js>); 052 * 053 * <jc>// Get the encoder</jc> 054 * IEncoder encoder = g.getEncoder(matchedCoding); 055 * </p> 056 */ 057public final class EncoderGroup { 058 059 /** 060 * A default encoder group consisting of identity and G-Zip encoding. 061 */ 062 public static final EncoderGroup DEFAULT = create().append(IdentityEncoder.class, GzipEncoder.class).build(); 063 064 // Maps Accept-Encoding headers to matching encoders. 065 private final ConcurrentHashMap<String,EncoderMatch> cache = new ConcurrentHashMap<>(); 066 067 private final String[] encodings; 068 private final List<String> encodingsList; 069 private final Encoder[] encodingsEncoders; 070 private final List<Encoder> encoders; 071 072 /** 073 * Instantiates a new clean-slate {@link EncoderGroupBuilder} object. 074 * 075 * <p> 076 * This is equivalent to simply calling <code><jk>new</jk> EncoderGroupBuilder()</code>. 077 * 078 * @return A new {@link EncoderGroupBuilder} object. 079 */ 080 public static EncoderGroupBuilder create() { 081 return new EncoderGroupBuilder(); 082 } 083 084 /** 085 * Returns a builder that's a copy of the settings on this encoder group. 086 * 087 * @return A new {@link EncoderGroupBuilder} initialized to this group. 088 */ 089 public EncoderGroupBuilder builder() { 090 return new EncoderGroupBuilder(this); 091 } 092 093 /** 094 * Constructor 095 * 096 * @param encoders The encoders to add to this group. 097 */ 098 public EncoderGroup(Encoder[] encoders) { 099 this.encoders = immutableList(encoders); 100 101 List<String> lc = new ArrayList<>(); 102 List<Encoder> l = new ArrayList<>(); 103 for (Encoder e : encoders) { 104 for (String c: e.getCodings()) { 105 lc.add(c); 106 l.add(e); 107 } 108 } 109 110 this.encodings = lc.toArray(new String[lc.size()]); 111 this.encodingsList = unmodifiableList(lc); 112 this.encodingsEncoders = l.toArray(new Encoder[l.size()]); 113 } 114 115 /** 116 * Returns the coding string for the matching encoder that can handle the specified <c>Accept-Encoding</c> 117 * or <c>Content-Encoding</c> header value. 118 * 119 * <p> 120 * Returns <jk>null</jk> if no encoders can handle it. 121 * 122 * <p> 123 * This method is fully compliant with the RFC2616/14.3 and 14.11 specifications. 124 * 125 * @param acceptEncoding The <c>Accept-Encoding</c> or <c>Content-Encoding</c> value. 126 * @return The coding value (e.g. <js>"gzip"</js>). 127 */ 128 public EncoderMatch getEncoderMatch(String acceptEncoding) { 129 EncoderMatch em = cache.get(acceptEncoding); 130 if (em != null) 131 return em; 132 133 AcceptEncoding ae = AcceptEncoding.forString(acceptEncoding); 134 int match = ae.findMatch(encodings); 135 136 if (match >= 0) { 137 em = new EncoderMatch(encodings[match], encodingsEncoders[match]); 138 cache.putIfAbsent(acceptEncoding, em); 139 } 140 141 return cache.get(acceptEncoding); 142 } 143 144 /** 145 * Returns the encoder registered with the specified coding (e.g. <js>"gzip"</js>). 146 * 147 * @param encoding The coding string. 148 * @return The encoder, or <jk>null</jk> if encoder isn't registered with that coding. 149 */ 150 public Encoder getEncoder(String encoding) { 151 EncoderMatch em = getEncoderMatch(encoding); 152 return (em == null ? null : em.getEncoder()); 153 } 154 155 /** 156 * Returns the set of codings supported by all encoders in this group. 157 * 158 * @return An unmodifiable list of codings supported by all encoders in this group. Never <jk>null</jk>. 159 */ 160 public List<String> getSupportedEncodings() { 161 return encodingsList; 162 } 163 164 /** 165 * Returns the encoders in this group. 166 * 167 * @return An unmodifiable list of encoders in this group. 168 */ 169 public List<Encoder> getEncoders() { 170 return encoders; 171 } 172}