001    /*
002     * Copyright 2007-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2015 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.asn1;
022    
023    
024    
025    
026    import static com.unboundid.asn1.ASN1Constants.*;
027    import static com.unboundid.asn1.ASN1Messages.*;
028    import static com.unboundid.util.Debug.*;
029    import static com.unboundid.util.StaticUtils.*;
030    
031    
032    
033    /**
034     * This class provides an ASN.1 null element, which does not hold a value.  Null
035     * elements are generally used as placeholders that can be substituted for other
036     * types of elements.
037     */
038    public final class ASN1Null
039           extends ASN1Element
040    {
041      /**
042       * A pre-allocated ASN.1 null element with the universal null BER type.
043       */
044      public static final ASN1Null UNIVERSAL_NULL_ELEMENT = new ASN1Null();
045    
046    
047    
048      /**
049       * The serial version UID for this serializable class.
050       */
051      private static final long serialVersionUID = -3264450066845549348L;
052    
053    
054    
055      /**
056       * Creates a new ASN.1 null element with the default BER type.
057       */
058      public ASN1Null()
059      {
060        super(UNIVERSAL_NULL_TYPE);
061      }
062    
063    
064    
065      /**
066       * Creates a new ASN.1 null element with the specified BER type.
067       *
068       * @param  type  The BER type to use for this ASN.1 null element.
069       */
070      public ASN1Null(final byte type)
071      {
072        super(type);
073      }
074    
075    
076    
077      /**
078       * Decodes the contents of the provided byte array as a null element.
079       *
080       * @param  elementBytes  The byte array to decode as an ASN.1 null element.
081       *
082       * @return  The decoded ASN.1 null element.
083       *
084       * @throws  ASN1Exception  If the provided array cannot be decoded as a null
085       *                         element.
086       */
087      public static ASN1Null decodeAsNull(final byte[] elementBytes)
088             throws ASN1Exception
089      {
090        try
091        {
092          int valueStartPos = 2;
093          int length = (elementBytes[1] & 0x7F);
094          if (length != elementBytes[1])
095          {
096            final int numLengthBytes = length;
097    
098            length = 0;
099            for (int i=0; i < numLengthBytes; i++)
100            {
101              length <<= 8;
102              length |= (elementBytes[valueStartPos++] & 0xFF);
103            }
104          }
105    
106          if ((elementBytes.length - valueStartPos) != length)
107          {
108            throw new ASN1Exception(ERR_ELEMENT_LENGTH_MISMATCH.get(length,
109                                         (elementBytes.length - valueStartPos)));
110          }
111    
112          if (length != 0)
113          {
114            throw new ASN1Exception(ERR_NULL_HAS_VALUE.get());
115          }
116    
117          return new ASN1Null(elementBytes[0]);
118        }
119        catch (final ASN1Exception ae)
120        {
121          debugException(ae);
122          throw ae;
123        }
124        catch (final Exception e)
125        {
126          debugException(e);
127          throw new ASN1Exception(ERR_ELEMENT_DECODE_EXCEPTION.get(e), e);
128        }
129      }
130    
131    
132    
133      /**
134       * Decodes the provided ASN.1 element as a null element.
135       *
136       * @param  element  The ASN.1 element to be decoded.
137       *
138       * @return  The decoded ASN.1 null element.
139       *
140       * @throws  ASN1Exception  If the provided element cannot be decoded as a null
141       *                         element.
142       */
143      public static ASN1Null decodeAsNull(final ASN1Element element)
144             throws ASN1Exception
145      {
146        if (element.getValue().length != 0)
147        {
148          throw new ASN1Exception(ERR_NULL_HAS_VALUE.get());
149        }
150    
151        return new ASN1Null(element.getType());
152      }
153    
154    
155    
156      /**
157       * Appends a string representation of this ASN.1 element to the provided
158       * buffer.
159       *
160       * @param  buffer  The buffer to which to append the information.
161       */
162      @Override()
163      public void toString(final StringBuilder buffer)
164      {
165        buffer.append("ASN1Null(type=");
166        toHex(getType(), buffer);
167        buffer.append(')');
168      }
169    }