1/*
2 * Copyright (C) 2011 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the
10 * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
11 * express or implied. See the License for the specific language governing permissions and
12 * limitations under the License.
13 */
14
15package com.google.common.collect;
16
17/**
18 * "Overrides" the {@link ImmutableMultiset} static methods that lack
19 * {@link ImmutableSortedMultiset} equivalents with deprecated, exception-throwing versions. This
20 * prevents accidents like the following:
21 *
22 * <pre>   {@code
23 *
24 *   List<Object> objects = ...;
25 *   // Sort them:
26 *   Set<Object> sorted = ImmutableSortedMultiset.copyOf(objects);
27 *   // BAD CODE! The returned multiset is actually an unsorted ImmutableMultiset!}</pre>
28 *
29 * While we could put the overrides in {@link ImmutableSortedMultiset} itself, it seems clearer to
30 * separate these "do not call" methods from those intended for normal use.
31 *
32 * @author Louis Wasserman
33 */
34abstract class ImmutableSortedMultisetFauxverideShim<E> extends ImmutableMultiset<E> {
35  /**
36   * Not supported. Use {@link ImmutableSortedMultiset#naturalOrder}, which offers better
37   * type-safety, instead. This method exists only to hide {@link ImmutableMultiset#builder} from
38   * consumers of {@code ImmutableSortedMultiset}.
39   *
40   * @throws UnsupportedOperationException always
41   * @deprecated Use {@link ImmutableSortedMultiset#naturalOrder}, which offers better type-safety.
42   */
43  @Deprecated
44  public static <E> ImmutableSortedMultiset.Builder<E> builder() {
45    throw new UnsupportedOperationException();
46  }
47
48  /**
49   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
50   * Comparable} element.</b> Proper calls will resolve to the version in {@code
51   * ImmutableSortedMultiset}, not this dummy version.
52   *
53   * @throws UnsupportedOperationException always
54   * @deprecated <b>Pass a parameter of type {@code Comparable} to use
55   *             {@link ImmutableSortedMultiset#of(Comparable)}.</b>
56   */
57  @Deprecated
58  public static <E> ImmutableSortedMultiset<E> of(E element) {
59    throw new UnsupportedOperationException();
60  }
61
62  /**
63   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
64   * Comparable} element.</b> Proper calls will resolve to the version in {@code
65   * ImmutableSortedMultiset}, not this dummy version.
66   *
67   * @throws UnsupportedOperationException always
68   * @deprecated <b>Pass the parameters of type {@code Comparable} to use
69   *             {@link ImmutableSortedMultiset#of(Comparable, Comparable)}.</b>
70   */
71  @Deprecated
72  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2) {
73    throw new UnsupportedOperationException();
74  }
75
76  /**
77   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
78   * Comparable} element.</b> Proper calls will resolve to the version in {@code
79   * ImmutableSortedMultiset}, not this dummy version.
80   *
81   * @throws UnsupportedOperationException always
82   * @deprecated <b>Pass the parameters of type {@code Comparable} to use
83   *             {@link ImmutableSortedMultiset#of(Comparable, Comparable, Comparable)}.</b>
84   */
85  @Deprecated
86  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2, E e3) {
87    throw new UnsupportedOperationException();
88  }
89
90  /**
91   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
92   * Comparable} element.</b> Proper calls will resolve to the version in {@code
93   * ImmutableSortedMultiset}, not this dummy version.
94   *
95   * @throws UnsupportedOperationException always
96   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
97   *             ImmutableSortedMultiset#of(Comparable, Comparable, Comparable, Comparable)}. </b>
98   */
99  @Deprecated
100  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2, E e3, E e4) {
101    throw new UnsupportedOperationException();
102  }
103
104  /**
105   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
106   * Comparable} element.</b> Proper calls will resolve to the version in {@code
107   * ImmutableSortedMultiset}, not this dummy version.
108   *
109   * @throws UnsupportedOperationException always
110   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
111   *             ImmutableSortedMultiset#of(Comparable, Comparable, Comparable, Comparable,
112   *             Comparable)} . </b>
113   */
114  @Deprecated
115  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2, E e3, E e4, E e5) {
116    throw new UnsupportedOperationException();
117  }
118
119  /**
120   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
121   * Comparable} element.</b> Proper calls will resolve to the version in {@code
122   * ImmutableSortedMultiset}, not this dummy version.
123   *
124   * @throws UnsupportedOperationException always
125   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
126   *             ImmutableSortedMultiset#of(Comparable, Comparable, Comparable, Comparable,
127   *             Comparable, Comparable, Comparable...)} . </b>
128   */
129  @Deprecated
130  public static <E> ImmutableSortedMultiset<E> of(
131      E e1,
132      E e2,
133      E e3,
134      E e4,
135      E e5,
136      E e6,
137      E... remaining) {
138    throw new UnsupportedOperationException();
139  }
140
141  /**
142   * Not supported. <b>You are attempting to create a multiset that may contain non-{@code
143   * Comparable} elements.</b> Proper calls will resolve to the version in {@code
144   * ImmutableSortedMultiset}, not this dummy version.
145   *
146   * @throws UnsupportedOperationException always
147   * @deprecated <b>Pass parameters of type {@code Comparable} to use
148   *             {@link ImmutableSortedMultiset#copyOf(Comparable[])}.</b>
149   */
150  @Deprecated
151  public static <E> ImmutableSortedMultiset<E> copyOf(E[] elements) {
152    throw new UnsupportedOperationException();
153  }
154
155  /*
156   * We would like to include an unsupported "<E> copyOf(Iterable<E>)" here, providing only the
157   * properly typed "<E extends Comparable<E>> copyOf(Iterable<E>)" in ImmutableSortedMultiset (and
158   * likewise for the Iterator equivalent). However, due to a change in Sun's interpretation of the
159   * JLS (as described at http://bugs.sun.com/view_bug.do?bug_id=6182950), the OpenJDK 7 compiler
160   * available as of this writing rejects our attempts. To maintain compatibility with that version
161   * and with any other compilers that interpret the JLS similarly, there is no definition of
162   * copyOf() here, and the definition in ImmutableSortedMultiset matches that in
163   * ImmutableMultiset.
164   *
165   * The result is that ImmutableSortedMultiset.copyOf() may be called on non-Comparable elements.
166   * We have not discovered a better solution. In retrospect, the static factory methods should
167   * have gone in a separate class so that ImmutableSortedMultiset wouldn't "inherit"
168   * too-permissive factory methods from ImmutableMultiset.
169   */
170}
171