jep使用

维护API很难。

我们正在维护非常复杂的jOOQ API。 但是就语义版本而言，我们遵循相对宽松的规则 。

当您阅读Brian Goetz和其他人关于在JDK中保持向后兼容性的评论时，我只能对他们的工作表示敬意。 显然，我们都希望最终移除Vector ， Stack ， Hashtable类的东西，但是在collection API周围存在与向后兼容相关的边缘情况，普通凡人不会想到。 例如： 为什么Java集合不删除通用的方法？

更好的弃用

使用Java 9，Jigsaw和模块化，这些新功能的主要驱动目标之一是能够“切断” JDK的各个部分，并在以后的发行版中轻轻弃用并删除它们。 作为改进的一部分， Stuart Marks AKA Deprecator博士建议使用JEP 277：“增强的弃用” 。

这样做的目的是通过一些附加信息来增强@Deprecated批注，例如：

• 不确定的 。 该API已被弃用，没有给出任何理由。 这是默认值; 今天隐含弃用的所有内容都有一个不合格的弃用原因。
• 谴责 。 该API已指定在将来的JDK版本中删除。 请注意，此处使用的“已谴责”一词是指要拆除的结构。 该术语并不意味着暗示任何道德谴责。
• 危险的 。 使用此API可能导致数据丢失，死锁，安全漏洞，错误结果或JVM完整性丢失。
• 过时的 。 不再需要此API，应删除用法。 不存在替代API。 请注意，OBSOLETE API可能标记为“已拒绝”。
• 放弃 。 该API已被较新的API取代，用法应从该API迁移到较新的API。 请注意，SUPERSEDED API可能会或可能不会标记为CONDEMNED。
• 已取消 。 调用无效或将无条件引发异常。
• 实验 。 该API并不是规范的稳定部分，它可能会不兼容地更改或随时消失。

在弃用东西时，重要的是能够传达弃用的意图。 也可以通过@deprecated Javadoc标记来实现，该标记可以生成任何类型的文本。

另一种更好的解决方案

上述主张存在以下问题：

• 它是不可扩展的 。 对于JDK库设计人员来说，以上内容可能就足够了，但是作为第三方API提供程序的我们将希望枚举中包含更多元素，而不是CONDEMNED，DANGEROUS等。
• 仍然没有纯文本信息 。 由于我们仍然无法正式向注释提供任何文本来阐明该注释，例如，为什么某事物“危险”的动机，因此该注释与Javadoc标记之间仍然存在冗余。
• “不推荐使用”是错误的 。 将UNIMPLEMENTED或EXPERIMENTAL标记为“已弃用”的想法表明了该JEP的变通方法性质，它试图在现有名称中增加一些新功能。

我感觉JEP太害怕触摸太多部分。 但是，将有一个非常简单的替代方法，它对每个人都好得多：

public @interface Warning {String name() default "warning";String description() default "";
}

无需将可能的警告类型的数量限制为有限的常量列表。 相反，我们可以使用@Warning注释，该注释可以包含任何字符串！

当然，JDK可以具有一组众所周知的字符串值，例如：

public interface ResultSet {@Deprecated@Warning(name="OBSOLETE")InputStream getUnicodeStream(int columnIndex);}

要么…

public interface Collection<E> {@Warning(name="OPTIONAL")boolean remove(Object o);
}

注意，虽然实际上不赞成使用JDBC的ResultSet.getUnicodeStream() ，但我们也可以向Collection.remove()方法添加提示，该方法仅适用于Collection类型，而不适用于其许多子类型。

现在，使用这种方法的有趣之处在于，我们还可以增强有用的@SuppressWarnings批注，因为有时，我们仅知道KnowWhatWeAreDoing™，例如在编写类似以下内容时：

Collection<Integer> collection = new ArrayList<>();// Compiler!! Stop bitching
@SuppressWarnings("OPTIONAL")
boolean ok = collection.remove(1);

这种方法可以一次性解决许多问题：

• JDK维护人员拥有他们想要的。 轻度弃用JDK的好工具
• 关于 @SuppressWarnings可能发生的事情的记录不完整的混乱最终将变得更加干净和正式
• 我们可以根据各种用例向用户发出大量自定义警告
• 用户可以在非常精细的级别上使警告静音

例如： jOOQ的动机是消除DSL equal()方法与不幸的Object.equals()方法之间的歧义：

public interface Field<T> {/*** <code>this = value</code>.*/Condition equal(T value);/*** <strong>Watch out! This is * {@link Object#equals(Object)}, * not a jOOQ DSL feature!</strong>*/@Override@Warning(name = "ACCIDENTAL_EQUALS",description = "Did you mean Field.equal?")boolean equals(Object other);
}

• 此处描述了该用例的背景： https : //github.com/jOOQ/jOOQ/issues/4763

结论

毫无疑问，JEP 277很有用。 但是它的范围也非常有限（可能不会进一步延迟Jigsaw吗？）但是，我希望JDK维护人员可以更彻底地处理生成此类编译器警告的主题。 这是DoTheRightThing™的绝佳机会

我认为上述“规范”并不完整。 这只是一个粗略的主意。 但是我曾希望作为API设计人员多次尝试这种机制。 为了向用户提供有关潜在的API滥用的提示，他们可以通过以下方式将其静音：

• @SuppressWarnings ，直接在代码中。
• 易于实现的IDE设置。 对于Eclipse，NetBeans和IntelliJ而言，对这些东西实施自定义警告处理将非常简单。

一旦有了@Warning批注，我们也许可以最后淘汰不那么有用的@Deprecated …

@Warning(name = "OBSOLETE")
public @interface Deprecated {
}

翻译自: https://www.javacodegeeks.com/2015/12/jep-277-enhanced-deprecation-nice-heres-much-better-alternative.html

jep使用