VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 1 | /* |
Brian O'Connor | a09fe5b | 2017-08-03 21:12:30 -0700 | [diff] [blame] | 2 | * Copyright 2016-present Open Networking Foundation |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package org.onosproject.yms.ych; |
| 18 | |
| 19 | import org.onosproject.yms.ydt.YdtBuilder; |
| 20 | import org.onosproject.yms.ydt.YmsOperationType; |
| 21 | |
| 22 | /** |
| 23 | * Abstraction of an entity which overrides the default codec. |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 24 | * <p> |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 25 | * YANG has it extension framework which allows vendor / implementation |
| 26 | * specific operation or extensions. The default CODECs will fail to handle |
| 27 | * such protocol requests. In such scenarios, the providers can register |
| 28 | * their specific CODEC's with the YANG codec utility to translate the protocol |
| 29 | * specific data to abstract YANG data tree, from which it can be translate into |
| 30 | * the YANG modelled java objects for the provider / driver to operate on the |
| 31 | * device. |
| 32 | */ |
| 33 | |
| 34 | public interface YangDataTreeCodec { |
| 35 | /** |
| 36 | * When the YMS need to encode simple protocol operation request, |
| 37 | * it will translate the YANG objects into an abstract YANG data tree and |
| 38 | * invoke this registered encode method. Protocol CODEC implementation |
| 39 | * needs to ensure the overridden method can handle any specific |
| 40 | * extension or representation of protocol data. |
| 41 | * The operation type will be set in YANG data tree builder. |
| 42 | * |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 43 | * @param ydtBuilder Abstract YANG data tree contains the operation |
| 44 | * request |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 45 | * @return protocol specific string representation. |
| 46 | */ |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 47 | String encodeYdtToProtocolFormat(YdtBuilder ydtBuilder); |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 48 | |
| 49 | /** |
| 50 | * When the YMS need to encode composite protocol operation request, it |
| 51 | * will translate the YANG objects into an abstract YANG data |
| 52 | * tree and invoke this registered encode method. Protocol CODEC |
| 53 | * implementation needs to ensure the overridden method can handle any |
| 54 | * specific extension or representation of protocol data. |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 55 | * <p> |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 56 | * The Initial chain of node in the YDT will have the operation type set |
| 57 | * to NONE to specify it is a resource identifier. The Resource |
| 58 | * information is maintained as a subtree to the resource identifier node. |
| 59 | * |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 60 | * @param ydtBuilder Abstract YANG data tree contains the operation |
| 61 | * request |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 62 | * @return composite response containing the requested operation |
| 63 | * information |
| 64 | */ |
| 65 | YangCompositeEncoding encodeYdtToCompositeProtocolFormat( |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 66 | YdtBuilder ydtBuilder); |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 67 | |
| 68 | /** |
| 69 | * When YMS decode simple protocol operation request it uses the |
| 70 | * registered decode method to translate the protocol data into a |
| 71 | * abstract YANG data tree. Then translate the abstract YANG data |
| 72 | * tree into the YANG modeled Java objects. |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 73 | * <p> |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 74 | * The CODEC implementation are unaware of the schema against which they |
| 75 | * are performing the codec operation, so YMS will send the schema |
| 76 | * registry on which the YANG data tree needs to operate, so the code |
| 77 | * implementation needs to pass this schema registry to the get a YDT |
| 78 | * builder. |
| 79 | * |
| 80 | * @param protocolData input string containing the simple |
| 81 | * protocol data which needs to be decoded |
| 82 | * @param schemaRegistryForYdt Schema registry based on which the YANG |
| 83 | * data tree will be built |
| 84 | * @param protocolOperation protocol operation being performed |
| 85 | * @return decoded operation request in YANG data tree |
| 86 | */ |
| 87 | YdtBuilder decodeProtocolDataToYdt(String protocolData, |
| 88 | Object schemaRegistryForYdt, |
| 89 | YmsOperationType protocolOperation); |
| 90 | |
| 91 | /** |
| 92 | * When YMS decode composite protocol operation request it uses the |
| 93 | * registered decode method to translate the protocol data into a |
| 94 | * abstract YANG data tree. Then translate the abstract YANG data |
| 95 | * tree into the YANG modeled Java objects. |
Shankara-Huawei | d5823ab | 2016-11-22 10:14:52 +0530 | [diff] [blame] | 96 | * <p> |
VinodKumarS-Huawei | af9c7a7 | 2016-08-30 19:43:39 +0530 | [diff] [blame] | 97 | * The CODEC implementation are unaware of the schema against which they |
| 98 | * are performing the codec operation, so YMS will send the schema |
| 99 | * registry on which the YANG data tree needs to operate, so the code |
| 100 | * implementation needs to pass this schema registry to the get a YDT |
| 101 | * builder. |
| 102 | * |
| 103 | * @param protocolData composite input string containing the |
| 104 | * protocol data which needs to be decoded |
| 105 | * @param schemaRegistryForYdt Schema registry based on which the YANG |
| 106 | * data tree will be built |
| 107 | * @param protocolOperation protocol operation being performed |
| 108 | * @return decoded operation request in YANG data tree |
| 109 | */ |
| 110 | YdtBuilder decodeCompositeProtocolDataToYdt( |
| 111 | YangCompositeEncoding protocolData, Object schemaRegistryForYdt, |
| 112 | YmsOperationType protocolOperation); |
| 113 | } |