001/* 002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. 003 * 004 * Copyright (c) 2015-2017 Oracle and/or its affiliates. All rights reserved. 005 * 006 * The contents of this file are subject to the terms of either the GNU 007 * General Public License Version 2 only ("GPL") or the Common Development 008 * and Distribution License("CDDL") (collectively, the "License"). You 009 * may not use this file except in compliance with the License. You can 010 * obtain a copy of the License at 011 * https://oss.oracle.com/licenses/CDDL+GPL-1.1 012 * or LICENSE.txt. See the License for the specific 013 * language governing permissions and limitations under the License. 014 * 015 * When distributing the software, include this License Header Notice in each 016 * file and include the License file at LICENSE.txt. 017 * 018 * GPL Classpath Exception: 019 * Oracle designates this particular file as subject to the "Classpath" 020 * exception as provided by Oracle in the GPL Version 2 section of the License 021 * file that accompanied this code. 022 * 023 * Modifications: 024 * If applicable, add the following below the License Header, with the fields 025 * enclosed by brackets [] replaced by your own identifying information: 026 * "Portions Copyright [year] [name of copyright owner]" 027 * 028 * Contributor(s): 029 * If you wish your version of this file to be governed by only the CDDL or 030 * only the GPL Version 2, indicate your decision by adding "[Contributor] 031 * elects to include this software in this distribution under the [CDDL or GPL 032 * Version 2] license." If you don't indicate a single choice of license, a 033 * recipient has the option to distribute your version of this file under 034 * either the CDDL, the GPL Version 2 or to extend the choice of license to 035 * its licensees as provided above. However, if you add GPL Version 2 code 036 * and therefore, elected the GPL Version 2 license, then the option applies 037 * only if the new code is made subject to such option by the copyright 038 * holder. 039 */ 040 041package javax.json; 042 043/** 044 * This interface represents an implementation of a JSON Merge Patch 045 * as defined by 046 * <a target=_blank href="http://tools.ietf.org/html/rfc7396">RFC 7396</a>. 047 * 048 * <EMBED CLASS='external-html' DATA-FILE-ID=LICENSE DATA-CIETName=JsonMergePatch> 049 * 050 * <BR /><BR />A {@code JsonMergePatch} can be instantiated with 051 * {@link Json#createMergePatch(JsonValue)} by specifying the patch operations in a JSON Merge 052 * Patch or using {@link Json#createMergeDiff(JsonValue, JsonValue)} to create a JSON Merge Patch 053 * based on the difference between two {@code JsonValue}s. 054 * 055 * <BR /><BR />The following illustrates both approaches. 056 * 057 * <BR /><BR />1. Construct a JsonMergePatch with an existing JSON Merge Patch. 058 * 059 * <BR /><DIV CLASS=SNIP>{@code 060 * JsonValue contacts = ... ; // The target to be patched 061 * JsonValue patch = ... ; // JSON Merge Patch 062 * JsonMergePatch mergePatch = Json.createMergePatch(patch); 063 * JsonValue result = mergePatch.apply(contacts); 064 * }</DIV> 065 * 066 * <BR /><BR />2. Construct a JsonMergePatch from a difference between two {@code JsonValue}s. 067 * 068 * <BR /><DIV CLASS=SNIP>{@code 069 * JsonValue source = ... ; // The source object 070 * JsonValue target = ... ; // The modified object 071 * JsonMergePatch mergePatch = Json.createMergeDiff(source, target); 072 * // The diff between source and target in a Json Merge Patch format 073 * }</DIV> 074 * 075 * @see <a target=_blank href="http://tools.ietf.org/html/rfc7396">RFC 7396</a> 076 * 077 * @since 1.1 078 */ 079public interface JsonMergePatch { 080 081 /** 082 * Applies the JSON Merge Patch to the specified {@code target}. 083 * The target is not modified by the patch. 084 * 085 * @param target the target to apply the merge patch 086 * @return the transformed target after the patch 087 */ 088 JsonValue apply(JsonValue target); 089 090 /** 091 * Returns the {@code JsonMergePatch} as {@code JsonValue}. 092 * 093 * @return this {@code JsonMergePatch} as {@code JsonValue} 094 */ 095 JsonValue toJsonValue(); 096}