ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132365844
########## File path: README.md ########## @@ -0,0 +1,102 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you 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. +--> + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is an API project with the goal of providing an extremely +stable library for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a string of bytes and associated utility classes for situations when +a raw byte array is not appropriate. + +Specifically, it provides a `ByteSequence` interface, analogous to Java's +`CharSequence`, an immutable `Bytes` implementation analogous to Java's +`String`, and a corresponding `BytesBuilder` analogous to Java's +`StringBuilder`. + +The provided classes have appropriate methods for serialization, and proper +equals and hashCode implementations, as well as a comparator for +`ByteSequence`, so they will be suitable for use in `Set`s and as keys in +`Map`s. + +An immutable bytes implementation makes it possible to pass data between APIs +without the need for performance-killing protective copies. This benefit is +compounded if this library is used by multiple projects, as the need to make +protective copies while passing data between a project and its dependency's API +is eliminated. + +This project aims to provide a fluent and intuitive API, with support for +conversions to/from other common types, such as `ByteBuffer`, `byte[]`, and +`CharSequence`/`String`. + +This project requires at least Java 8, and supports `Stream` and functional +APIs where appropriate. + +See this [blog post][blog] for some additional background. + +## Safe for APIs + +Using an external library in a project's API poses some risks to that project, +especially if it and its dependencies depend on different versions of that +library. This project attempts to mitigate those risks, so that it can be used +safely by other projects. + +This project is made safe for reuse in other projects' APIs by adopting the +following principles: + +* Using [Semantic Versioning 2.0.0][semver] to make strong declarations about + backwards-compatibility +* Strongly avoid breaking changes (avoid major version bumps), so that projects Review comment: Ugh, I hate that new "feature" to Java 9, especially since it defaults to "false". Personally, I think all deprecations are subject to removal. I really don't want to start putting "forRemoval = true" in all my deprecation annotations just so users don't think "this isn't going away". I'd rather they'd have created a new annotation for things which are expected to remain, but should not be used by users, which generated similar compiler warnings as Deprecated. This one is really going to cause confusion with defaulting to false. A lot of them are going to be set to false simply because nobody's explicitly setting them to true. Users are going to be disappointed when they disappear. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
