content: /*
   * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  package java.security.cert;
  
  import java.io.IOException;
  import java.io.OutputStream;
  import java.io.Serializable;
  
  /**
   * This interface represents an X.509 extension.
   *
   * <p>
   * Extensions provide a means of associating additional attributes with users
   * or public keys and for managing a certification hierarchy.  The extension
   * format also allows communities to define private extensions to carry
   * information unique to those communities.
   *
   * <p>
   * Each extension contains an object identifier, a criticality setting
   * indicating whether it is a critical or a non-critical extension, and
   * and an ASN.1 DER-encoded value. Its ASN.1 definition is:
   *
   * <pre>
   *
   *     Extension ::= SEQUENCE {
   *         extnId        OBJECT IDENTIFIER,
   *         critical      BOOLEAN DEFAULT FALSE,
   *         extnValue     OCTET STRING
   *                 -- contains a DER encoding of a value
   *                 -- of the type registered for use with
   *                 -- the extnId object identifier value
   *     }
   *
   * </pre>
   *
   * <p>
   * This interface is designed to provide access to a single extension,
   * unlike {@link X509Extension} which is more suitable
   * for accessing a set of extensions.
   *
   * @since 1.7
   */
  public interface Extension {
  
      /**
       * Gets the extensions's object identifier.
       *
       * @return the object identifier as a String
       */
      String getId();
  
      /**
       * Gets the extension's criticality setting.
       *
       * @return true if this is a critical extension.
       */
      boolean isCritical();
  
      /**
       * Gets the extensions's DER-encoded value. Note, this is the bytes
       * that are encoded as an OCTET STRING. It does not include the OCTET
       * STRING tag and length.
       *
       * @return a copy of the extension's value, or {@code null} if no
       *    extension value is present.
       */
      byte[] getValue();
  
      /**
       * Generates the extension's DER encoding and writes it to the output
       * stream.
       *
       * @param out the output stream
       * @exception IOException on encoding or output error.
       * @exception NullPointerException if {@code out} is {@code null}.
       */
      void encode(OutputStream out) throws IOException;
  }
  